FishMarket 1.0/FishMarket v1.0.iso/fishies/201-225/disk_202/vlt/vltstory.zoo/vltstory

Text File | 1989-05-04 | 165KB | 3,571 lines

                                VLT, The Story






                               Marvin Weinstein


                        Stanford Linear Accelerator Center
                     Stanford University, Stanford, CA 94305

 (Edited by Willy Langeveld)
 (To be reedited by Marvin Weinstein)

 Appendices by

  Willy Langeveld

   Department of Physics
   University of California
   Riverside, CA 92521

 (Edited by Marvin Weinstein)
 (To be reedited by Willy Langeveld)



  Once upon a time there was a project to find out how well an Amiga could be
used as a color graphics terminal and TeX workstation at SLAC (Stanford Linear
Accelerator Center). It immediately became clear to all concerned that before
the project could really begin one would have to have a terminal emulator which
could successfully talk to the IBM 3081 and all the VAX'es on the site.
Moreover, it had to compete in quality with the Ann Arbor Ambassador GXL
terminals which were already in use at the laboratory. Unfortunately, at the
time there was no commercial program which fit the bill, so Willy Langeveld, who
had already been  playing around with Tektronix emulation, started  hacking up a
public domain VT100 emulator written by Dave Wecker et al., with a little help
from Marvin Weinstein. The program VLT represents the culmination of these
labors. We hope it will provide a baseline from which future efforts to provide
terminal emulation for use within the context of an IBM and DEC mainframe
environment will build.

Not much of the original code of VT100 remains; nevertheless, we owe a debt of
gratitude to the authors of the original program because it kept us on the air
and functioning while the changes were taking place. Without its example to
follow we probably never would have gotten as far as we did. Kudos also go to
Joanne Dow who allowed us to use her code for handling the serial port, Charlie
Heath for the use of his file requester, Carolyn Scheppner for the palette tool
and Dave Betz for his Bmodem code. Having this stuff to fall back upon made the
job of cleaning up the relevant portions of the old VT100 code much easier and
helped make things run faster and more smoothly. Also thanks to Jim Kent, Jim
Mackraz and Tom Rokicki for various little snippets of code!


  What It Does At SLAC: Terminal Emulation

The original purpose of this terminal emulation program was to provide one of
the crucial links in the establishment of the Amiga as a feasible, cost
effective terminal + TeX Workstation at SLAC. This dictated that it had to do
certain things and do them well.

    First, it had to allow one to log onto IBM and VAX mainframes over
various communications links, telephone lines, the Micom Switch and the Bridge.
This meant that various parity modes and Xon/Xoff protocols had to be supported
and that it should be easy to switch between these modes. Thanks to the native
software of the Amiga and Joanne Dow's code, VLT supports baud rates from 300
to 19200, 15 parity protocols (including the 7E1 required by the IBM) and four
different handshaking protocols (including Xon/Xoff).

  The terminals most in use at SLAC are Ambassador GXL's. These have 24
programmable function keys and allowed the system to reprogram various
attributes of the terminal in order to automatically switch between 24, 32 and
43 line mode on the IBM. Since the Amiga keyboard only has 10 function keys
along the top of the keyboard alternative ways of getting the same functionality
had to be explored. The solution was to provide the user with several choices:

 o  The numerical keypad on the right hand side of the Amiga keyboard
functions as it does on a VT100, and so all of the IBM function keys used at
SLAC can be accessed from there in exactly the same way that they would be
accessed on a true VT100.

 o  The ten function keys at the top of the keyboard can be programmed by
the user so as to provide 40 functions. This is accomplished by allowing
programming of the keys F1---F10 themselves,  and the two-key combinations SHIFT
+ F1---F10 (i.e., hold down the shift key and hit any function key), ALT +
F1---F10 and CTRL + F1---F10.

 o  At the bottom of the screen, a total of 30 function gadgets can be
displayed. These gadgets are on-screen software objects which may be activated
by moving the mouse cursor over them and clicking the left mouse button. They
are programmed by default to emulate the way in which the function keys on an
Ambassador work, but they can be user-programmed in a variety of ways which will
be explained later. For those users who do not wish to have these function
gadgets displayed at the bottom of the screen we have provided a means for
removing and restoring them at will.

 o   VLT provides an additional 10 programmable function keys accessed
by holding down the Amiga key to the right of the space bar and hitting any one
of the numbers 1,2,...,0 at the top of the  keyboard.

  Since we are talking about color terminal support, it was important that
the terminal allow the mainframe to send escape sequences in order to tell the
Amiga to use different colors to display bold, underlined, italic and reverse
video fields in  different colors, as would be done by an IBM 3270 terminal.
VLT supports these features and the escape sequences which should be sent by
the host in order to activate them are documented in Appendix I.

  VLT is designed to provide the same sort of Tektronix emulation that
one has become used to on the Ambassador GXL terminal: it opens a second screen
for graphics, independent of the alphanumeric screen. As in the case of the
Ambassador GXL the second screen provides the functionality of a Tektronix 4014
terminal, however, since we wished to provide color support, it also handles
many of the escape sequences recognized by a Tektronix 4105 terminal. This means
that it will handle the color commands which will be available under the SLAC
facilities TopDraw and Unified Graphics. The details of the Tektronix emulation
and the  escape sequences that need to be sent for which commands are given in
Appendix II and III.

  The Amiga is naturally a mouse + keyboard oriented machine. Once a person
gets used to this he or she often wishes to have a way to use the mouse to
handle cursor positioning and interactive graphics support when dealing with the
mainframe. VLT  allows the user to use the mouse for cursor positioning, etc.
Those who like to do everything from the keyboard can turn this feature off.


   What It Does At SLAC: File Transfer
   -----------------------------------

As already noted, in addition to using the Amiga as simply a high quality color
graphics terminal, we also wished to be able to use it for local TeX and ASCII
document preparation and TeX previewing. In order to do this we needed a good
editor, a first rate TeX program and a means of getting files to and from the
mainframe. The editor we have chosen for this purpose is TxEd Plus, the TeX
program is Tom Rokicki's AmigaTeX and the file transfer is built into VLT .
Since this writeup is meant to play the role of a VLT user's manual, we will
not go further into these issues. The remainder of this section will discuss the
file transfer protocols which VLT supports.

IBM mainframes, being what they are, do not in general like to talk to other
than IBM hardware. Therefore, some very special protocols had to be developed in
order to make it possible to transfer files from an IBM mainframe to a desktop
computer such as the Amiga. The most popular protocol for carrying on such
transfers with an IBM mainframe is named Kermit (yes, for the frog). Kermit is
one of a number of transfer protocols which are supported on the SLAC system,
another one being PC-TRANS, which is used with the Ambassador emulation (ABE)
provided for IBM PC's on the IBM mainframe. Since Kermit is a much more widely
used file protocol and therefore not so site specific, we chose it for inclusion
in VLT. Also, it didn't hurt that this was one of the protocols provided
in Wecker's original code.

      In any file transfer process of this type there are two separate
programs which must be run together, one  on the mainframe and one on the local
(desktop) computer. VLT provides two ways for handling the details of this
process. One way is to do everything by hand using the keyboard or menu options
which will be discussed in the section giving the details of the file transfer
process. This of course necessitates that you know how Kermit works both on the
Amiga and on the mainframe. To learn how the mainframe version works all you
have to do is log onto VM and type   HELP KERMIT   Obviously, the
virtue of providing a general file transfer mechanism of this type is that it
allows you to handle file transfers using Kermit which are not going to SLAC's
IBM 3081; the disadvantage is that the user has to carry out many repetitive
steps and faces the danger of locking up the IBM since file transfer to and from
the mainframe can be a somewhat fragile process.

        However, since VLT interfaces to AmigaREXX (AREXX), it is possible to
write macros (also called scripts or execs) to handle the details for you.
Macros for the handling of ASCII (text, not binary) file transfers to and from
the mainframe are included, This is one example of the general AREXX scripting
capablity built into VLT.  The file transfer process is carried out by these
REXX execs which can be modified by the user to suit his own purposes if and
when he or she learns a little about the AREXX language. For those who are
familiar with REXX on the mainframe, AREXX is a full implementation of REXX on
the Amiga,  with extra features which allow access to many of the Amiga's
special capabilities. A discussion of the way in which VLT interfaces to the
general Amiga multi-tasking environment and AREXX in particular will be given
later, and an example will be discussed. Note, that in what follows we will
often assume that you have a setup which includes AREXX and WSHell. If you do
not have these programs you should since VLT is really designed to function as
one component in a system of modular software using AREXX as the process
manager. Both products can be ordered from

            William S. Hawes
            P.O.Box 308
            Maynard, MA 01754
            (617) 568--8695


Although VLT will run perfectly well without AREXX and WShell, the full
scripting capabilities will not be available to you unless you are operating
within the environment created by these two programs. Another product which you
should have is FastFonts from Microsmiths. It can be purchased as part of the
program TxEd-Plus, an AREXX integrated editor. This product is available from

           Microsmiths, Inc.
           P.O. Box 561
           Cambridge, MA 02140
           (617) 354--1224

Fastfonts allows you to replace the system font with one which looks a lot
better and also speeds up the writing of text to the screen by a significant
amount, thus making for much smoother terminal operation.

Another protocol which has come into wide use is the Xmodem protocol (and its
derivatives such as YMODEM and ZMODEM). As with Kermit it requires that a pair
of programs be run together, one on the mainframe and one on the desktop
computer. Although this protocol cannot be used with IBM mainframes it can be
used with VAX'es on site.  An XMODEM program that runs on the VAX (VAXXMODEM)
can be obtained from Willy Langeveld (WGLP09 at SLACVM). As with Kermit two
modes of operation are possible. First, file transfer can be carried out
entirely by hand by starting the mainframe program and then handling the Amiga's
part of the deal from the menu options. On the other hand, it is a simple chore
to rewrite the AREXX scripts which handle Kermit file transfers to handle XMODEM
transfers to and from the VAX.

         Last but not least there is the simplest method
of all for accomplishing a file transfer to the desktop, ASCII capture. In this
mode you simply set the program to save everything which comes to the terminal
screen to a file. On an IBM, this works only if you set the IBM into scrolling
mode by logging on in line mode (VMLINE or PACE) and then typing

   TYPE MYFILE FT FM

This is the fastest method for downloading a file to the Amiga, but it does no
error checking, so it is not the safest mode for long files. In addition to
ASCII capture we have ASCII send: this lets the Amiga type a file to the the
mainframe. Unfortunately, this mode of file transfer does not always work well
since most mainframes do not handle stuff coming at it this fast.  However, this
method works if one is logged onto many bulletin boards or with online services
such as BIX and CompuServe.


         Installation

  If you got VLT on a 3.25 in disk labelled VLTDISK: then you should find,
in addition to the program VLT itself, several files and directories which you
have to install on your boot disk in order to make it possible for you to use
all the features the program has. If on the other hand you have obtained VLT
on a disk labelled SLACDISK: then you already have a bootable disk containing
the necessary files and all you should do is diskcopy it to another disk and use
the copy as your boot disk. In that case, unless you want to create your own
custom boot disk, you can skip this section entirely. (I will assume in this
write-up that the reader has at least a passing familiarity with the way in
which the Amiga's filing system organizes files into directories,
subdirectories, etc. Those people who use the VAX'es will be familiar with this
concept, however IBM mainframe users will find that it takes a little getting
used to. I suggest you read your manual or the writeup    Getting To Know Your
Amiga in order to gain a passing familiarity with the file system.)

   What's On the Disk?

The disk distributed to you has two files in the root directory (these are the
files you see listed when you type the command

   DIR

in any CLI (Amigaese for Command Line Interface, i.e. a window which behaves
like a terminal where you are prompted for commands). These files are called VLT
and VLT.INFO . The first file is the terminal program itself and the second is
the Workbench icon which allows you to run the program by opening up a window on
the Workbench and clicking on the ICON. Even if you are an afficionado of the
CLI (for example, if you come from the IBM-PC world) you ought to take a look at
the icon. It is BIG and impressive. In particular, look at the little lights on
the modem (Willy is really proud of that touch). Both of these files should be
copied to the root directory of your boot disk. To copy these over (assuming you
have two disk drives) type

   COPY VLTDISK:VLT TO DF0:

(note, I have implicitly assumed that your boot disk is in drive DF0: and that
the distribution disk is in the drive called  DF1:). Then type

   COPY VLTDISK:VLT.INFO TO DF0:

At this point you have transferred both the terminal program and its icon to the
root directory of your boot disk. You might think that you are done now, however
that is not the case. In order for VLT to work at all you need to copy several
other files to various directories on your boot disk. Some of the files listed
below are not required, but allow you to use VLT's full potential.
The directories which contain files which you should transfer are

      VLTDISK:C

      VLTDISK:LIBS

      VLTDISK:S

      VLTDISK:REXX

      VLTDISK:FONTS

      VLTDISK:DOCS

In the sections to follow we will list the contents of each directory and
subdirectory on VLTDISK: and explain what to do with them and why.

If you have obtained VLT by downloading the archive VLTnpmmm.arc, some of the
files mentioned may be missing. In that case, read all the README files in the
archive and execute all the EXECUTEME's (we assume such users are experienced
enough to know what to do).


  VLTDISK:LIBS

This directory contains five files:

 arp.library
 rexxarplib.library
 rexxmathlib.library
 rexxmathsbii.library
 screenshare.library

The first file is the library of routines belonging to the AmigaDOS Replacement
Project (ARP). This is a project undertaken by various Amiga developers to
replace the Amiga's native DOS commands with a set of commands which are smaller
(i.e. take up less room on your boot disk) and which provide a more consistent
user interface. This file must be copied to the directory  DF0:libs  on your
boot disk. To do this type

   COPY VLTDISK:ARP.LIBRARY TO DF0:LIBS

The next file, rexxarplib.library, is a library (written by Willy) which allows
you to access some ARP functions (among which Charlie Heath's file requester)
and several other requesters and message windows from within AREXX script files.
This is extremely useful and allows for a uniform interface among different
pieces of AREXX capable software. In particular it means that macros written for
VLT , AmigaTeX and TxEd Plus have access to the same Amiga gadgets for
posting messages and obtaining input; hence, once you are used to them in one
application you know how to use them whenever you run across them.

The file rexxmathlib.library is another AREXX library (Willy again) which makes
all the special math functions which are in the IEEE Amiga math library callable
from AREXX. This makes the Amiga into a programmable calculator par excellence.
The documentation which explains the functions callable from
rexxarplib.library and rexxmathlib.library are all on the disk in the directory
VLTDISK:docs. A special version of the library is called rexxmathsbii.library.
This library can be used instead of rexxmathlib.library if you have a StarBoard
II (by MicroBotics) with a Multi-Function Module and a 68881 math coprocessor.

Finally, the file screenshare.library must be copied. It allows the requesters
of rexxarplib.library to appear on VLT's screen even if it is a CUSTOM screen
(if you don't know what this means, don't let it bother you).

   VLTDISK:C

This directory contains the ARP1.1 replacements for the functions of the same
name found in the directory Workbench:c on your boot disk. If you wish to
install these commands in place of the ones provided with your Amiga, and this
is highly recommended, you simply type

   COPY VLTDISK:C TO DF0:C

Notice, that all these commands make use of the file arp.library which you
were instructed to copy in the previous paragraph. Now you understand that it
is important to copy arp.library first!

  VLTDISK:S

You will find three files in this directory:

 VTPrefs.dat
 TekPrefs.dat
 ovlt.init

Copy these files to the directory DF0:S by typing

   COPY VLTDISK:S TO DF0:S

The first two files are configuration files which contain information which
defines the values for all the parameters which can be set from the VLT menus
and from scripts. When you first run the program VLT by either clicking on its
icon on the Workbench, or by typing

   RUN DF0:VLT

(assuming that you have not copied VLT to some other location like RAM: or
VD0:), it will look in the directory assigned to S: (usually DF0:S) for the
files VTPrefs.dat and TekPrefs.dat . If they do not exist VLT will start up
with a set of built-in defaults which will probably not correspond to the
configuration which you wish to use. We will come back to the way in which you
can modify these files in the next chapter when we discuss VLT 's user
interface.

In addition to the parameter files VTPrefs.dat and TekPrefs.dat, VLT will look
for a file called vlt.init . It is a file that may contain any valid VLT
primitive script command. As such, it can serve a similar role to VTPrefs.dat
and TekPrefs.dat in that it allows the user to define the default values
established for the terminal configuration when you first run it. It differs in
that it is a text file that can be edited. If you wish VLT to use this file
every time you turn on simply rename ovlt.init to vlt.init by typing

   RENAME DF0:S/OVLT.INIT DF0:S/VLT.INIT

Once you have done this, commands in this file will be executed and values given
in this file will override the ones specified in VTPrefs.dat and TekPrefs.dat.

   Why have files of this sort? The reason is really quite simple. Often a
user has to log on to more than one kind of mainframe (for example, the IBM and
a VAX) and he wishes to have a different configuration on each machine. In that
case he can tell VLT to use different configurations for different machines by
the way he invokes the program.

    NOTE:  this option is only available if you start the program
from a CLI and not if you click on the Workbench icon. The way in which you
invoke different startup configurations is explained in the next chapter.

  VLTDISK:REXX

This directory contains examples of AREXX macros which can be automatically
invoked by choosing the first option in the macros menu when the program is
running. If you have AREXX as part of your setup (and once again we urge that
you do) then you should type the following two commands

   MAKEDIR DF0:REXX
   COPY VLTDISK:REXX TO DF0:REXX

The discussion of these execs (or macros, or scripts) and what they do
will appear in the next chapter.

    VLTDISK:FONTS

This directory contains several sets of fonts. The font called vltgraph.font and
its accompanying directory vltgraph with the files 8 and 11 is necessary.
It also contains a font which is a modification of Charlie Heath's
siesta font and which we find easy to read. If you don't like it you can always
fire up the font editor on your Extras Disk and change it, or make your own
font. This font will, however, only be used by VLT if you have FastFonts.
To copy this directory, type

   COPY VLTDISK:FONTS TO DF0:FONTS ALL

Note, you cannot leave out the word ALL since this tells DOS to create
the subdirectories DF0:FONTS/MYSIESTA and DF0:FONTS/VLTGRAPH and copy the
contents of

  VLTDISK:FONTS/MYSIESTA and VLTDISK:FONTS/VLTGRAPH to it.

  VLTDISK:DOCS

This directory contains files which you don't have to copy to your boot disk,
but which may be consulted for information about the way in which you use the
ARP1.1, rexxarplib and rexxmathlib commands. If you own TxEd or TxEd Plus use
them to examine the files. If you don't own a text editor you can see what files
are in this directory by typing

   DIR VLTDISK:DOCS OPT A

and to see the contents of a particular document named foo.doc type

   TYPE VLTDISK:DOCS/FOO.DOC

and the contents of the documents will be typed to the screen. To stop the file
from scrolling off the screen the easiest thing is to hit the space bar (or any
other key). To start it up again hit backspace.



         The User Interface

   Starting Up

  As was mentioned in the previous chapter, there are two ways to start VLT .
The simplest way is to click on the Workbench disk icon found on the right hand
side of the Workbench screen. This will cause a window to open and in this
window there will be found an icon whose purpose, thanks to Willy, you will not
be able to help identifying. Move your mouse cursor over this icon and quickly
click the left mouse button twice (this is called    double-clicking ). At
this point a particularly silly looking cloud will appear to tell you that the
program is loading, and in a few moments the appearance of your screen will
change dramatically (everything will disappear) because you are now under the
control of the terminal program.

The second way in which you can reach the same point is from the CLI environment
and it is done by typing

   RUN DF0:VLT

(assuming that you have the program in the root directory of your boot disk).
This method will be preferred by people used to working on the mainframe and who
are unsure of their mouse acuity. Actually, it is the more flexible method
because you can provide the command with several parameters which affect the way
in which it is invoked. The full syntax of the command is

   RUN VLT [+I startup.file] [script1] [script2] .....

or

   RUN VLT [-] [script1] [script2] .....

Clearly this arcane form of the command requires some explanation.

As we noted in the previous section VLT has the capability of using plain text
configuration files in order to define the baud rate, screen colors, etc. which
it will use after the program has loaded. Such configuration files, of which
ovlt.init is an example, can also contain most of the basic scripting commands
of VLT. The way in which one writes script files and the commands which VLT
understands will be fully discussed in the section titled MACROS, at this
juncture the only thing you need to know is that such scripts exist and you can
tell VLT to execute any number of them in a specified order at startup.
If you only type

   RUN VLT

what happens is that VLT first looks at the file VTPrefs.dat, which contains
default values (which you can change) of all its internal paramters. Then it
looks for a file called vlt.init, either in the current directory, or in the
directory assigned to S:. If you type the command with the  +I  option,
then you are telling VLT that it should use a file with another name instead
of vlt.init. In the above example that would be startup.file . (Notice, that the
[ ] indicate that the parameter is optional). If you type the command with the
 -I  you indicate the program should be run without looking for any .init
file.  Any other file names specified on the command line are the names of
script files, that the program should run after the startup file has completed
and when VLT is fully up and running.

The distinction between ordinary script files and startup files exists because
there are certain VLT commands which can only be executed at startup, and
conversely, other commands can only be executed when VLT is  running.

Hence, you might have two configuration files called S:IBM.INIT and S:VAX.INIT
and perhaps two scripts called S:IBMLOGON.SCP and VAXLOGON.SCP. Then, if you
type

   RUN VLT +I  S:IBM.INIT S:IBMLOGON.SCP

it will setup according to the defaults specified in the file S:IBM.INIT and
then execute the logon sequence specified in the file S:IBMLOGON.SCP. (Recall:
S: is the logical name usually assigned to the directory DF0:S .) If, on the
other hand you type

   RUN VLT +I S:VAX.INIT S:VAXLOGON.SCP

it will set up the defaults specified in S:VAX.INIT and run the logon procedure
specified in S:VAXLOGON.SCP. If you are the proud owner of WSHell then you can
add the commands

   ALIAS IBMVLT = VLT +I S:IBM.INIT S:IBMLOGON.SCP

   ALIAS VAXVLT = VLT +I S:VAX.INIT S:VAXLOGON.SCP

to your startup sequence and save yourself a lot of typing.

In either event, no matter which procedure you choose to get started, once your
screen goes blank you have entered the domain of VLT and the time has come to
become acquainted with what we refer to as its user interface.


   Menus, Menus, Menus

Assuming that you could not wait and have followed our previous instructions and
now find yourself staring at a blank screen (this emulates what an ordinary
terminal looks like when you turn it on) you now are wondering what you should
do. If you have hooked up your modem or Micom box/cable to the Amiga's serial
port as per the instructions in your manual, all you really have to do is hit
return once or twice and things might go very smoothly and you will be ready to
log on to your favorite mainframe. Of course Murphy's Law being what it is
things are probably not going to go like this and you will have to reset some of
VLT 's defaults so that it will work with your modem and mainframe combination.
The question we will address in this section is how you go about doing this and
how, when you are finished doing this, how you save the results of your efforts.

If you are an Amiga novice the first step is to get acquainted with Amiga menus
in general and VLT 's in particular. To display a menu put your hand on your
mouse, hold down the    right   mouse button. At the top of the screen the
following words will appear:

  VLT   Comm   Transfer  Macros  Screen  Operation Graphics

These are the names of the seven drop down menus which belong to VLT 's
alphanumeric screen (i.e. the screen on which text is displayed). Moving the
cursor over any one of these names (still holding the right mouse button down)
causes the menu associated with that name to drop down. Each of these menus has
several items (or options) displayed on it and some options even have
sub-options (or sub-items) associated with them. Sub-items are revealed only
when you slide the mouse cursor down along the menu until it is pointing to the
correct item.

The various menu options allow you to change some of the default parameters
VLT opened with, start a file capture or transfer, launch an AREXX or VLT
script, switch to another window or screen, etc. To select a menu option you
simply slide the mouse cursor over the option until the choice you wish is
highlighted and then holding the mouse steady you release the right mouse
button. For keyboard oriented individuals, we have also provided keyboard
shortcuts for selecting most of these options. To select an option from the
keyboard, hold down the Right-Amiga key (i.e., the key to the right of the space
bar with the letter A on it) and type the letter you found shown to the right of
the item text in the menu. Thus, to start a capture you can select the Capture
Session option in the VLT menu using the mouse, or alternatively hold down the
Right-Amiga key and hit the letter O.

We will devote the remainder of this section to listing each of the menu options
and explaining what they do. Since there are separate menus associated with the
text and graphics screens we will discuss each case separately.



  Menus Which Belong to the Text Screen


     VLT
       Capture Session
       End Capture
       Save Screen
       Save Configuration
       Version
       Exit

   The VLT Menu

  Capture Session

This option can be selected from the menu as shown, or by using the alternate
keyboard command A-O (hold down the right amiga key and type O). All commands
that have keyboard alternatives are indicated in the menu in this way. This
option allows you to capture anything which is coming to the screen to a file.
If you select this option Charlie Heath's file requester will appear. It will
look something like the picture below. Since this is a file requester you will
not be surprised to know that it is requesting that you give it the name of the
file into which the program is to save the captured text. This requester will
appear again and again so it is worth spending a few minutes describing the way
in which it is used. There is a special paragraph at the end of this section
which explains the file requester in great detail.

For now, suffice it to say that the requester is actually a window  (just like
any of the windows which open on the Workbench) which is endowed with several
gadgets. Two obvious gadgets are the rectangular boxes at the top and bottom of
the window. The first one is labelled  drawer  and the second  file .
These are string gadgets in which you can type names of files and directories.

Every Amiga filename consists of two parts: the path which specifies the
disk:directory/subdir/subdir/.../  that a file resides in and the file's
name. Hence we have files like

  DF0:DEVS/KEYMAPS/USA1

or

  DF0:FONTS/MYSIESTA/8 .

In the first case the path is DF0:DEVS/KEYMAPS and the filename is USA1. In the
second case the path is DF0:FONTS/MYSIESTA and the filename is 8. Directories
(paths) are really the same as the `drawers' you see when you look at the
Workbench screen when some of the disk icons are open. Charlie Heath therefore
chose to label the string gadget wherein you are to type the path designation
drawer. The second string gadget, into which the filename is to be typed
is labelled file  .

If you wish to do everything by hand simply select the top string gadget by
clicking upon it with the mouse (use the left mouse button) and then type the
name of the directory where you want to store the captured file. For capture
files it usually is wise to use RAM: or VD0: (which is the name of a recoverable
ram disk). Suppose you type VD0:. When you're done, either hit return, or use
the mouse and click in the file gadget. Either action will activate the second
gadget. Here, you type the filename you wish VLT to use. Type, e.g., JUNK. At
this point, if you are happy, all you have to do is click on the gadget labelled
OKAY and the requester will disappear and from that moment on VLT will save
everything it gets from the mainframe into a file named VD0:JUNK. If you wish to
give up on the whole thing click on the CANCEL gadget.

Note that we recommend capturing to RAM: (or VD0:) since it is faster than
capturing to a floppy disk. Also, should for some reason a system crash occur
while VLT is writing to a disk, there is a (small) chance that you will
wind up with an unreadable floppy.

Selecting the Capture Session  option from the VLT menu a second time will
suspend file capture. If you do this a little message box will appear on your
screen saying that this has happened. This message box will go away as soon as
you hit any key or click on your mouse. When capture is suspended nothing that
comes to the screen goes to the capture file. Reselecting  Capture Session
toggles capture on again and everything coming to the screen is again being
saved into the previously defined file. You can toggle capture on and off can
go on as many times as you wish.

  End Capture

To shut down file capture completely and close the capture file all you
have to do is select this option.

This completes the discussion of capture to a file, however the astute user will
have immediately noticed that there is a lot of other stuff going on in
Charlie's requester.

An Aside About The File requester


The first thing we should discuss is that if you use the mouse and click on the
drawer gadget you then can type the directory  where a file you want to create
should be stored or where a file you wish to  access resides. If you now hit the
return key the names of all the files already stored in that directory will
appear in the region between the drawer gadget and the file gadget. If there are
a sizeable number of files in this directory then it will take a few moments for
the names of all files to be loaded into memory. If there are many files not all
names will be visible at once; however, you can view them all by scrolling
through the list of names in memory, that is what the    slider   (also
called proportional gadget) on the right hand side of the requester is for. This
is another type of screen gadget which works like a knob sliding in a track. To
use it place your mouse over the knob, hold down the left mouse button (this
grabs the knob) and slide your mouse up or down. As you do this the list of file
names in the directory will scroll past. Another thing that will happen when you
first click on the knob is that the list will be sorted alphabetically. This is
useful, for example,  when you wish to transfer a file to the main frame, or
when you wish to specify the name of an AREXX macro or VLT script file you wish
to have executed. In such an event, instead of typing the name of the desired
file into the file gadget, you can take a shortcut; namely, move your mouse
cursor over the name you wish to appear in the file gadget and click your left
mouse button once. Automagically, the name will appear in the file box below.
Now, in order to indicate that you have made your choice all you have to do is
click on the OK gadget, or simply hit the RETURN key, whichever is easiest to do
at the moment. Actually, there is yet another way to combine the steps of
choosing the name you wish to put in the string gadget and then signalling that
you are done; simply double click on the name of the file. (   Double click
means click the left mouse button quickly twice in a row).

Okay, now that we know about scrolling through file names in a directory, and
the shortcuts for getting the name into the file string, you naturally want to
know if there is a shortcut for getting the
directory/subdir/subdir/.../  name into the drawer gadget.    Yes there
is.   In fact, it works entirely the same way. When you click on a name that
starts with the highlighted letters (dir) , this directory specification
will appear in the drawer gadget. However, sometimes the directory you want
isn't listed because it is on another disk, perhaps. The trick is to use the
right mouse button. If you position the mouse cursor over the body of the
requester and click on the right mouse button the names of all the devices on
which files are stored will appear. Devices are things whose names finish in a
: , that is names like DF0:, DF1:, RAM:, VD0:, etc. (NOTE: The Amiga allows
you to pull a trick and assign whole path names to a `logical' device by typing,
for example,

   ASSIGN REXX: DF0:REXX

inside a CLI or by putting it in your startup-sequence. If you have done this
then Charlie Heath's requester will be smart enough to display this for you when
you click the right mouse button and you will be saved plumbing the depths of
various directories to find a specific file.) If you click on one of these names
(using the left mouse button) that name will appear in the drawer gadget, and
then the names of the files and directories stored here will appear in the
window between the drawer and file gadgets. Files will simply be represented by
their names. As mentioned, directories will be prefaced by the symbol
(dir)  and this will appear in a different color than the file names. If you
want one of the files whose name is displayed simply click upon it and it will
appear in the file gadget. If you want a file in one of the directories, then
click on the name of the directory and it will appear in the drawer gadget. Of
course, when the directory name appears in the drawer gadget then the names of
the files in that directory will replace the names of the files that were
displayed previously. The set of files that are stored in the top directory
level are said to be in the    root   directory, other  files are said to be
inside subdirectories. To get back the list of files that lay outside this
directory click on the parent gadget. First the directory name will revert to
the name of the parent directory and the list of names of files in the parent
directory will be redisplayed.

Very often when you look inside a directory you will find that it contains other
directories, which are referred to as subdirectories (kind of like a Russian
doll). You can keep peeling away at these subdirectories, like peeling the
layers of an onion, until you find the file you are looking for. Remember, if
you go into a subdirectory and realize you have gone a layer to deep, simply
click on the parent gadget and you will be returned to the previous directory.

The last thing to discuss is the CANCEL gadget, what could that be for? Right,
if you wish to abort the whole process you just started and have nothing happen
you click on the cancel gadget and the requester disappears into the night
leaving no trace of its passage. This finishes our aside on Charlie Heath's
requester.

  Save Screen Contents

This command doesn't do anything at present, except to tell you it isn't
currently implemented.

  Save Configuration

This command is very important in that it allows you to save the settings you
have made like baud rate, number of lines, macro key settings, colors, etc. to
the file S:VTPrefs.dat . All you have to do is configure things the way you want
and then select this option. If you already had a VTPrefs.dat file, the current
settings will replace the ones in that file. Note, that VLT looks for this
file in two places: first it will look in the directory where you were when you
started it up, and if the file is not there, VLT will look in the S:
directory. If you didn't have a VTPrefs.dat yet, VLT will create it and store
it in the current directory. (NOTE: S: is, at boot time, ASSIGN'ed to DF0:S. If,
however, you change this assignment VLT will  look for VTPrefs.dat in a
different directory).

  Version

This does nothing but bring up a message telling you what version of the program
you are using. You should include this in any correspondence about bugs since it
will tell us how old your version of the program is.

  Exit

This command does exactly what it says: it shuts down the terminal program.
It is best to log off from your mainframe before selecting this option.


This ends the list of commands available from the first menu on the text screen.
Next let us take a look at the commands available from the second menu on the
text screen.



      Comm
         Baud
         Parity
         Protocol
         Send Break
         Hang Up
         Echo

   The Comm Menu

  Baud

If you select the Comm  Menu you will see a second menu box appear to the
right of the selected menu item; this is our first example of a submenu. When a
submenu appears this means that there are several options associated with the
main menu choice and you have to pick one (or more) of them. To do this keep
holding the right mouse button down and slide the cursor to the right (not up or
down or you will change menu item and the submenu will disappear, or a submenu
associated with another item will appear in its place) until the highlighted
area appears in the submenu. When this happens move around in the submenu in the
same way as you would in a main menu and select the item you want by positioning
the cursor over it and releasing the right mouse button. If your mouse acuity is
not yet up to snuff you might find this operation a little tricky at first, but
practice will soon make perfect. In the case of the    Baud  item the submenu
will show the choices 300, 1200, 2400, 4800, 9600 and 19200. These are the baud
rates which VLT supports. Most SLAC users will have either 1200 or 2400 baud
modems at home and so for remote use you should probably select one of these two
choices. For use at SLAC through the Micom switch or the Bridge, the correct
choice is 9600 baud. Eventually, 19200 will be supported at SLAC and then this
becomes a possible choice. For now, if you make this choice and then hit the
space bar be warned that the terminal program will hang up and you will have to
reboot. This is not a bug in VLT, it appears to be a bug in the serial device
which is a program which comes with the machine. We are hopeful that it will
soon be fixed.

  Parity

   Parity is an outmoded technique for error detection which most
non-IBM computers pretty much ignore unless the user insists upon it.
Unfortunately IBM mainframes still insist on getting a specific parity and if
this is not set correctly you will not be able to log on to the main frame.
(Actually, at SLAC it is not the mainframe, but rather the Series 1 which we use
to allow the mainframe to communicate with non-IBM hardware.  This is a fine
point, however, and knowing it will not change the fact that you can't log on.)
If you select the    Parity  item in the    Comm  menu you will be presented
with a submenu which will allow you to choose all of the parity setting which
the Amiga supports in hardware. In addition to the (to some) familiar even and
odd parity settings (with one or two stop bits) there are the less familiar mark
and space parities. For SLAC users you really only need to know two settings. To
log onto the IBM mainframe    always   select    7E1  . To log onto Tymnet
and bulletin boards with modems you will often have to use    8N1 .

  Protocol

   This item refers to the type of handshaking that the
computer does with terminals in order to guarantee that data is not sent to or
from the computer too fast for either the terminal or mainframe to keep up. Both
the mainframe and the terminal have buffers which store the characters coming
from their correspondent to handle temporary overloads; however, if as in the
case of graphics, a huge amount of information is coming down the wire, there
has to be a way for one device to tell the other to shut up until he has
finished handling what it already has gotten. The Amiga provides several choices
of commonly used protocols, however at SLAC we only use one called xON/xOFF.

  Break

  Since there is no break key on the Amiga keyboard we have it
included as a menu option. This command has the alternative keyboard sequence
R-A B  (i.e. hold down the Amiga key to the right of the space bar and type
B). This key is necessary on Tymnet and in line mode (e.g. VMLINE or PACE) but
has no use in full screen mode on the IBM.

  Hang Up

   Sometimes you want to drop your connection from the serial
port (or Modem, Micom Switch, Bridge Box, etc) without leaving the terminal
program. This menu choice does that by simply shutting down the serial port for
a short time. Its keyboard alternative is ra H .

  Echo

   Terminals tend to operate in one of two possible modes depending
upon what the mainframe is doing. Either you type a character at the keyboard
and the terminal puts it up on the screen (`echos' it) and sends it to the
mainframe simultaneously, or the terminal sends the character to the mainframe
and the mainframe sends back a signal telling the terminal what to put up on the
screen. The first alternative is called    local echo   the second
remote echo . For logging on to SLAC the correct prescription is to select this
item to be    Off  in the submenu. You will immediately recognize that the
wrong choice has been made if you see that everything you type appears doubled
on the screen. As you will see by examining the submenu there are alternative
keyboard commands for turning local echo on and off.

This ends our discussion of the menu items which have to be set in order to
establish a connection to the mainframe. The next menu contains the selections
which establish the protocols you will use to send files to, and receive files
from, the mainframe.


    Comm
      Send File
      Receive File
      Protocol
      Kermit Options
      XMODEM Options
      Translate Options

   The Transfer Menu

  Send File

Since VLT supports three different kinds of file transfer we have chosen to
define general send and receive commands which do different things depending
upon other software switches which have been set. Thus this menu item is the one
you choose to initiate a file transfer from the Amiga to the mainframe. What
will happen after you select this menu option depends upon the choices which are
checked in items three through six of this menu. In any event, after you have
selected this item Charlie Heath's file requester will appear and you can use it
to find the file which you wish to send. Once the path and filename are in their
appropriate string gadgets simple click on OK and the file transfer will start.
While file transfer is going on a message box will appear and it will keep you
apprised of how the transfer is proceding.

In general in order to send a file to or from the mainframe a program has to be
run at    both   ends. These menu options only control what is happening at
the Amiga end of the process, you have to learn how to run Kermit or XMODEM at
the mainframe end by reading the documentation available there. In the next
section where we discuss the    Macros  menu we will talk about IBM specific
AREXX execs which handle the transfer at both ends for SLAC users.

For those SLAC users who wish to do something special, or who don't have AREXX
up and running, the simplest form of file transfer from the Amiga to the
mainframe is done as follows:

  First, type

   KERMIT RECEIVE FN FT FM

and wait for the kermit prompt which says that it is ready for file transfer.
Most of the time the screen will be cleared first. Sometimes if you are logged
on in full screen mode something will happen (like a message coming to you from
somewhere) to force the terminal into holding mode. You will recognize this by
the fact that HOLDING... will appear at the bottom right hand corner of the
screen. To get rid of this problem hit either the ENTER key or the CLR gadget on
the screen (presuming the PFkey gadgets are visible).

   Next, when everything is set up then select the    Send File  option
from the    Comm  menu.

      NOTE  in order to abort a file transfer which has hung up (i.e. you
see nothing happening in the message window) hit the ESC key. In the case of
Kermit an abort signal is sent each time you hit the escape key and it takes six
such signals to abort a transaction. After you have aborted a transaction you
should hit return a few times to make sure you have left the mainframe Kermit
program, or at least, that you have gotten its attention.

  Receive File

This performs the file transfer in the opposite direction, i.e. from the
mainframe to the Amiga. Once again this option controls what the Amiga does, not
what is going on on the mainframe. As before, for people who have AREXX running
the    Macros  menu provides an option for selecting an AREXX exec which will
handle file transfer to the Amiga from the FILELIST environment on the IBM.

If you do not have AREXX or wish to handle things by yourself, all the IBM user
has to do is type

   KERMIT SEND FN FT FM

and then when the screen clears and the message to procede is typed simply
select the receive file option. This of course presupposes that the remaining
menu options have been set up so that this mode of Kermit file transfer is
chosen as your default. Again, to abort a transfer hit the ESC key six times in
a row (not too fast).

  Protocol

This is the menu item which allows you to choose the basic protocol which is to
be used by the    Send File  and    Receive File  commands. When you select
this menu you will be presented with a submenu which has three options
displayed: ASCII transfer, Kermit and XMODEM. Each option can be set by the
indicated alternate keyboard commands shown next to the subitem names.

   ASCII transfer  is the simplest and fastest option, however it does no
error checking and so it is not the best way to handle long documents.
Nevertheless, if you wish to use it for file transfer from the IBM, go back to
the VLT menu description and read about Capture Session: the Receive File
command will tell you to use exactly that, if ASCII is selected.

If you want to send files this way to a mainframe, beware of the fact that many
mainframes can't handle very fast input. In fact, the IBM and VAXes at SLAC
usually don't like ASCII transfers to them at all. Many bulletin boards and
online services do allow this, though. Simply set up the editor on the bulletin
board in input mode and then select the    Send File  option. As in all other
cases you will be presented with a file requester which you can use to find the
Amiga file you want to send.

   Kermit transfer  is the protocol of choice for sending files to and from
the mainframe if you wish to send binary files (i.e. compiled programs) or wish
to have error checking performed during the transfer. The way to do a simple
file transfer was already explained in the previous paragraph. Note that if you
use this method then you must set your various options using the    Kermit
Options  submenu.

   XMODEM transfer  is not available for transfer to and from the IBM, however
it can be used for transferring files to and from the VAXes at SLAC. To get the
companion program VAXXMODEM for the VAX get in touch with Willy Langeveld,
WGLP09 at SLACVM. If you select this protocol then you have to set your XMODEM
default parameters using the    XMODEM options submenu .    NOTE  XMODEM
transfers are aborted in the same way as Kermit transfers; namely, you hit the
ESC key.

  Kermit Options

When you select this option a submenu will appear which allows you to choose
among two different ways of using Kermit, and which also provides you with a way
of setting the default directory into which files coming to the Amiga are to be
placed. To change the default directory simply select the    Change Directory
option from the submenu. When you do this a simple requester will appear which
contains a single string gadget. The current default directory will be displayed
in this gadget. All you have to do is replace the displayed string with another
of your choosing.

The other three options control the way in which Kermit is used. Up to now we
have discussed using Kermit in the mode wherein file transfers are handled by
running Kermit on the mainframe each time you wish to carry out a file transfer.
This method is selected by the first option,    Send/Receive . There is
however a second way of using Kermit and that is in    server   mode. In this
mode Kermit runs continuously on the mainframe and blocks all keyboard input,
however in that case the Amiga can control all file transfer from its end. To
use this option select    Host is Server . (If you have read the documentation
on the IBM then you might want to know that then the receive command implements
the    KERMIT GET  command.) If you set up for    Host is Server  then
selecting    Receive File  will bring up a requester which wants you to fill
in the name of a file on the mainframe. The disadvantage of using this mode is
that you cannot use FILELIST, etc., in order to find the name of a file which
you have forgotten. For those who have AREXX the Filelist_to_Amiga macro
provides a more convenient way of accomplishing mainframe to Amiga file
transfers.

The last option in the submenu is the    Kermit Bye . This option is necessary
if you are running the mainframe Kermit in server mode in order to tell it you
are finished and want it to terminate itself and return control of the terminal
to you. Remember, while Kermit is in server mode all keyboard input to the IBM
is blocked.

Notice, that this version of Kermit supports also what is known as `long packet'
kermit. For details on how to use that feature on the mainframe refer to your
local expert.

  XMODEM Options

Choosing this command brings up another submenu which allows you to choose the
type of XMODEM error checking which will be used in file transfer, as well as
the size of the packets which will be sent. Selecting the first option sets
error checking to consist of a simple check sum and uses short blocks for file
transfer. The second uses the same simple error checking but transfers packets
which have a length of one kilobyte. Since long packets are used this file
transfer goes faster, but with a greater chance of error. The next two choices
use a more complicated form  of error checking (CRC). The third choice specifies
short packets and the last choice specifies long packets.

  Translate Options

The final menu item brings up a submenu which controls the way in which binary
files are transferred and the way in which files are assigned default names
based upon the name they had on the mainframe. In general, to transfer an ASCII
file you wish to select the second option, CR/LF -> LF, as your default. This
is because on the IBM the end of a line of text is terminated with both a
carriage return and a line feed character, whereas on some other machines the
end of a line is signified simply by a line feed. Obviously, when ASCII files
are sent to the mainframe the opposite translation takes place if this option is
selected. To verify that this option is switched on look for a check mark to the
left of this item on the submenu. No check mark means that no such translation
is taking place.

The first option,    No translation , is only selected when a binary file is
being transferred (binary files are executable programs on either the mainframe
or the computer, or the output of graphics programs). In order to carry out a
binary file transfer to the IBM you have to set up both the mainframe and Amiga
properly. This is slightly more complicated to do than it was in the case of
ASCII file transfer. First go to the    Transfer  menu and select    No
translate  from the    Translate Options  submenu. To transfer a binary file
to the IBM you first set up the mainframe Kermit by typing

   KERMIT

and then you wait for the prompt to appear, at which point you type

   SET FILE BINARY
   RECEIVE FN FT FM

When the screen clears you are ready to go to the menu and select    Send
File . When the file transfer completes you have to leave Kermit by hitting
RETURN once or twice to get its attention and then type

   QUIT .

To get a binary file from the IBM to the Amiga you proceed in the same way
except that you give the IBM the command

   SEND FN FT FM

after setting the file to be binary, and you select the    Receive
File  option on the Amiga.

The final submenu option simply tells VLT whether or not to automatically to
convert names on the mainframe to lower case on the Amiga.

This completes our discussion of the menu commands which control file transfer.
Next we turn to the menu which controls VLT 's rather sophisticated scripting
capabilities.



     Macros
       AREXX Macro
       VLT Macro
       Abort VLT Macro
       Keyboard Macro
       Program Mode

   The Macros Menu

VLT can be programmed by the user to perform highly specialized operations on
two levels. On the low level, you can write scripts in VLT's own simple command
language. On the higher level, you can combine this simple command language with
AmigaREXX, if available. These scripts can be executed by specifying the name of
the script file after selecting from the menu which type of script you want to
execute, or by assigning one of eighty programmable keyboard sequences to
execute such a script file or an in-line script command.

  AREXX Macro

When you select this menu option the file requester appears and displays the
files found in your    rexx:  directory (usually you will have assigned
rexx:  to be either DF0:REXX or VD0:REXX) having file extension    .vlt . For
SLAC users we have included a sample  bf rexx  directory on the distribution
disk and it contains four sample AREXX macros (or scripts), two of which make it
easier to handle file transfer to and from the IBM, one which simply resets the
IBM if something messes up the screen and you don't know what to do, and one
which opens a TxEd Plus session on your Workbench screen. The names of these
files are:

    o rexx:Amiga_to_IBM.vlt
    o rexx:Filelist_to_Amiga.vlt
    o rexx:Reset_IBM.vlt
    o rexx:Open_Txed.vlt

To execute one of these files simply double click on it, or single click on it
and then click on the OK gadget. The file transfer macros will explain
themselves when you invoke them.

The explanation of what is in these macros and a list of the commands which are
understood by VLT will be given in the next section devoted to writing
scripts.

  VLT Macro

As we already noted, all of the commands which VLT understands can be run from
a file with file extension    .scp . Examples of such files will appear in the
next section. The file requester which appears when you select this menu option
automatically assumes that these files will be found in your current directory;
however, if you keep them elsewhere you can find them and execute them in the
same way as you find any file.

The difference between AREXX macros and VLT script files is that AREXX allows
for scripts written in a powerful BASIC-like language. Also, AREXX scripts run
asynchronously with VLT itself. These scripts allow you to carry out various
local operations, modify files, etc. and then to carry out various terminal
operations when appropriate. This can be anything, e.g. opening a file,
searching it for relevant information, or changing something in it, and then
transferring it automatically to the mainframe when your local procedure is
finished. VLT scripts, on the other hand, are limited in what they can do and
run under the control of the VLT program itself.

  Abort VLT Macro

As we said, since AREXX macros run independently of VLT they do not interfere
with its operation and if they abort the error messages are sent to a CLI. Since
VLT scripts do not run in this way there must be a way to abort a script once
it has started. Selecting the    Abort VLT Macro  accomplishes this feat for
you.

  Keyboard Macro

Selecting this menu option brings up a submenu which allows you to carry out the
operation that is equivalent to the keyboard command ra  n (where n stands
for a number from 0 to 9 to be found on the top row of the keyboard).

  Program Mode

Selecting this menu option reveals a submenu which gives you a choice of having
program mode    On  or    Off ; the default is of course having program mode
off. If one wishes to reprogram the behavior of the function keys, on screen
PFkey gadgets or any ra  n sequence, all one has to do is set program mode on
and then hit the appropriate sequence. When this is done a requester will appear
which will display the command which is currently assigned to this key. All you
have to do is change this string to another string and then hit RETURN; the
requester will then disappear. Aside from the thirty on-screen gadgets and the
R-A n sequences, the function keys are programmable by themselves, as well as
when either the SHIFT, CTRL or  ALT key are pressed simultaneously. When you are
finished reprogramming the keys that you wish to change simply turn program mode
off and then go back to the    VLT  menu and select the    Save
Configuration  option. VLT uses the ARP conventions for embedding escape,
control, linefeed, etc. characters in strings; this is all explained in the next
section devoted to writing scripts.

    Screen
       Clear Screen
       Screen to Back
       Select Screen Type
       Number of Colors
       Select Colors
       Number of Lines
       Number of Columns
       Amount of Prescroll
       Rendering Mode

   The Screen Menu

The menu options provided in this menu are concerned with setting various
properties of the text screen. In order to fully understand how some of the
commands work you have to understand that, in addition to being able to open
multiple windows on the Workbench screen, the Amiga supports the concept of
multiple custom screens. Following the desktop metaphor you can think of the
screen as the desktop and the windows, which belong to a given screen, as pieces
of paper, or file folders, which can be placed anywhere on a given desktop but
which cannot be moved from one desk to another. Multiple windows can be opened
on a given screen and when such a window is opened it allows us to look inside a
given folder.

         Windows may contain arbitrarily different contents, however all of the
windows which open on a given screen share certain display characteristics. For
example, all windows on a given screen have the same number of colors available
to them. The Workbench Screen (this is the screen which you see when you first
boot) can display only four colors. You can use the Preferences tool to set
these four colors to be any four chosen out of a palette of 4096 possible
colors, however once you have done this then all  windows which open on the
Workbench screen use the same four colors.  Windows also inherit their display
characteristics from the screen they are on. For example, if the screen is
interlaced (i.e. this is the default for SLACDISK) then the windows which open
on it will be too.

         Screens and windows differ in a very important way. In general, most
windows can be resized and moved around on their screen by using the mouse to
grab their drag and resizing gadgets. I say, in general, because it is possible
to open windows which have neither drag gadgets, nor resizing gadgets, nor close
gadgets, nor front to back gadgets, etc.; in fact, one can open windows which
have no borders at all. Nevertheless, in general, windows can be moved
horizontally and vertically, they can overlap one another, they can be opened
and closed, and their sizes can be changed. Screens are not this flexible.
Screens never have close gadgets (they open and close only under the control of
a program) and they cannot be resized. Also, screens must occupy the full width
of the display, although they can slide up and down to reveal anything which
lies behind them. Thus, like windows, screens can overlap one another and also,
like windows, they can have front to back gadgets. In other words, if a screen
has a drag bar at the top you can grab it with a mouse and slide it down to
reveal a screen in back of it, or you can click on its front to back gadget to
place it in back of any other screen which is open; however you cannot move it
to the right or left. Thus, if more than one screen is open, say screen A and
screen B, then A can be moved in front of B, or B can be moved in front of A by
clicking on their front to back gadgets,  if they have them. If there are back
to front gadgets on the screen they  will be located in the right hand corner of
the drag bar.

         VLT allows you to open both the text and graphics windows either on
the Workbench screen, or on separate custom screens. If you open on the
Workbench screen then your Workbench windows can be moved in front of the
terminal screen. This can be very useful if, for example, you wish to shrink a
CLI or application window to a small size and keep an eye on what is going on in
that window while you are doing something on the mainframe. The disadvantages to
opening the terminal program on the Workbench screen is that the displays are
limited to only four colors and the disk icons will be obscured. If you open a
custom screen then you can have up to eight colors on the text screen (to
provide for full color highlighting by the mainframe) and up to sixteen colors
on the graphics screen. If you open on a custom screen then you can set all the
colors for that screen while you are running the program and save these values
to your configuration files.

In order to give you the best of both worlds VLT provides menu options which
allow you to change your current screen characteristics at will without shutting
down the program. Also, since in order to be able to display the maximum number
of lines we open the VLT window without a drag bar, front to back gadgets,
close gadgets, etc., we provide keyboard and menu options to control the
positioning of the VLT window (and/or screen) relative to the Workbench
screen.

Having provided you with this review of basic facts about windows and screens
(read your Amiga manual for more information) let us turn to the commands in the
Screen  menu and see what they do for you.

  Clear Screen

This command does just what it says, it provides a local way of clearing the
screen without sending anything to the mainframe.

  Screen to Back

Technically, this command does different things depending upon whether the VLT
text window is open on  the Workbench screen or a custom screen. If you are on
the Workbench screen then it simply puts the VLT text window behind all of the
other windows on the Workbench screen. Thus, if prior to running VLT you
clicked on the various disk icons and opened windows which display other icons,
these windows will come to the front, so will any CLI windows which are open on
the Workbench. If however you have not clicked on any of these icons and there
are no CLI windows open on the Workbench screen, then this command will do
nothing. Once VLT is running there are only two things you can do to get at
the disk icons on the Workbench screen. One thing is to quit VLT , the second
thing is to move VLT to a custom screen, do what you want about the disk icons
and then, if you wish, put VLT back on the Workbench screen.

If you have VLT opened on a custom screen, this command will move all VLT's
screens in back of the Workbench screen.

  Select Screen Type

This is the item you select in order to change the current status of the VLT
text window and move it to and from the Workbench screen. When you select this
item a submenu appears with the choices,    Custom ,    Workbench ,
Interlaced  and    Non--Interlaced . If you select    Workbench  then the
text window will be opened on the Workbench screen. In that case it inherits the
number of colors and display characteristics of the Workbench screen and the
Interlace  and    Non--Interlaced  options will do nothing. If you select
Custom  then VLT opens a custom screen, independent of the Workbench
screen, for the text window; then you may choose this screen to be either
interlaced or non-interlaced.

  Number of Colors

This option allows you to select the number of colors that can be displayed on
the terminal text screen. Since the number of colors which can be displayed on a
Workbench screen is fixed to be four, this option only works if you have already
selected your    Screen Type  to be    Custom . If you are on a custom
screen then you have the option of using 2, 4 or 8 colors on your text screen.

  Select Colors

If you select this option then a palette requester appears on your screen. This
gadget works just like the one in preferences and allows you to interactively
change the colors on your screen by moving the sliders with the mouse. To change
a color simply click on the square showing that color and then move the R (red),
G (green) and B (blue)  sliders until you change the color to one closer to your
heart's desire. If, for example, the red slider is moved all the way to the left
than the amount of red in the color you are making will be zero; if, on the
other hand it is all the way to the right then you will have added the maximum
amount of red to the color.

  Number of Lines

If you are logging on to the mainframe at SLAC it will always set the number of
lines on the screen to be 24 until you change it by issuing the command

   MODEL 3 -- for 32 lines

or

   MODEL 4 -- for 43 lines

If you are not on the IBM, then you might wish to change the number of lines to
be displayed without relying upon the mainframe to do it for you. In this case
simply select this menu option. When you do this a requester will appear and the
number of lines which are currently being displayed will be shown in the string
gadget. Simply modify this number and hit RETURN and the new default number of
lines will be established. If you wish to make this the number of lines which
are to be used every time you run VLT just choose the    Save Configuration
option after making this change.

  Number of Columns

VLT in principle allows you to set the screen to display any number of
columns. The limitations upon what can actually be displayed are the size of the
screen and the size of the font being used. Thus, although you could, in
principle display 132 columns, since we do not have a font small enough for this
purpose we would advise against it. You can however use this setting to affect
where the text appears in the VLT window. If you use 80 columns, then it will
be roughly centered; however, if you use 85, for example, it will be moved left
on the screen. Note, that for some applications on your mainframe, 80 columns
may be required.

  Amount of Prescroll

This option is of interest primarily to VAX users who are likely to want to use
VLT in scrolling mode and who want it to scroll at least as fast as an
Ambassador. Since scrolling the screen is a fairly time consuming process,
scrolling through files with many short lines can start to slow everything down
unless one does something to cut down on the number of scrolls. The solution
adopted here is to simply look ahead about 100 characters at the text coming from
the mainframe and, if there are many carriage returns, simply scroll a number of
lines in one step. Prescroll determines the maximum number of lines which will
be scrolled at once. We have found 8 to be a number which provides fairly smooth
scrolling without sacrificing much in the way of speed. Setting the prescroll
variable proceeds in exactly the same way as setting the number of lines, or the
number of columns.


  Rendering Mode

This option allows you to affect the way in which VLT handles highlighting,
etc. as it is sent from the mainframe. If you select a custom, eight color,
screen and select the    Color  option from the    Rendering Mode  submenu,
then highlighted, unhighlighted, protected, unprotected (or equivalently, bold,
underlined, reverse video and italic) will be displayed by different colors. If
you select the    Normal  option then normal text will be displayed in one
color and all highlighted and protected fields will be displayed in another
(highlighting) color. If you select the    Quick  option, then instead of
displaying highlighted material in a different color it will be displayed in
bold face type, or indeed as originally intended, in reverse video or italic or
underlined. This mode is provided in order to speed up scrolling yet further,
since in this mode text is being rendered only onto what is effectively a two
color screen. This option, together with a prescroll setting of 8, is sufficient
to provide scrolling which is faster than that of an Ambassador terminal at
9600 baud. Even further speed-up can be gained by using no more than four colors
on your text screen. If you prefer to live in non-interlaced mode, the text
update speed is increased by another factor of two (the effective update speed
has been measured under these conditions to be of the order of 26 kbaud).

    Operation
       Wrap
       Numeric Keypad
       Application Cursor
       Swap BS<->Delete
       Help Key=LF
       Shift-Tab= ESC TAB
       Function Key Gadgets
       Mouse Support
       Beep Volume

   The Operation Menu

This menu controls display characteristics of the terminal and various things
having to do with the way in which keys on the keypad behave. It also controls
whether or not you get an audible or visual beep.

  Wrap  This controls whether or not the terminal automatically handles
wrapping at the end of a line. The default setting is off, as the mainframe
usually takes care of this for you in most situations.

  Numeric Keypad   Ordinarily the numeric keypad is set up to operate in
function key mode. This is useful on the VAX and on the IBM. On the VAX the
keypad is used in the same manner as it is used on a VT100. When logged onto the
IBM it is used to access the 24 PFkeys that are available on the Ambassador, IBM
3270, etc., terminals. To shut off this option and use the numeric keypad so
that unshifted characters provide numbers etc., simply select this option.

  Application Cursor  This feature is there in order to give the user
control over the way in which the cursor keys (the ones with arrows on them
arranged in a T between the alphabetic and numeric keypad) operate. When
deselected these keys behave as expected on the IBM. Normally you would leave
this option deselected and VAX editors will reprogram these keys as necessary.

  Swap BS<->Delete   This is provided as a courtesy to VAX users who
wish to interchange the function of the backspace and delete key (the backspace
key is the key with the arrow just to the left of the delete key).

  Help Key = LF   Since the Amiga keyboard does not provide a labelled
linefeed key we have allowed the user, if he so desires, to program the Help key
to perform this function. Selecting this key allows you to use the Help key to
perform the same function as the LF key on an Ambassador. However, since the
Amiga 1000 has a different numeric keypad layout, the help key otherwise has the
same function as the + key on Amiga 500/2000's. If you own an Amiga 1000, you
can program the function keys 1 through 4 to play the role of the top four
keys on the A500/2000 numeric keypad (VT100 PF1 through PF4).

  Shift-Tab = ESC TAB  When this option is selected, the shifted TAB key
(the one with the two arrows at the left hand side of the keyboard)  will send
the sequence ESC TAB to the mainframe, which effectively for SLAC VM means back
tab. When not selected, the shifted TAB key just sends the same as the unshifted
TAB key.

  Function Key Gadgets   Since some users would prefer not to have the
mouse operated function key gadgets on the screen, and would rather spread 43
(or more) lines of text over  a greater area, we have provided this switch which
turns the function key gadgets on or off. This means that you can operate with
the gadgets turned off and get them back when you want to lean back and mouse
around simply by selecting the menu option or typing ra P.

  Mouse Support   When this option is selected then positioning the
cursor on the screen and clicking the left mouse button will tell the mainframe
to move your cursor to that position on the screen. It provides a substitute for
using the arrow keys on the cursor application pad. This is very useful on the
mainframe when in Xedit, etc. but does not necessarily work on all mainframes.

  Beep Volume   Since we do not recommend the use of a Commodore monitor
for terminal emulation because of the flicker problem it is highly unlikely that
the monitor you purchase will have a built in speaker. Because of this you will
either have to go out and purchase a small speaker with a built-in amplifier or
hook up the outputs on the Amiga 2000 to your stereo in order to get an audible
beep. If you have a speaker available you set the volume of the beep by
selecting this item and typing a number from 1 to 60 in the string gadget which
appears. If you do not have a speaker available, then setting this number to
zero will provide you with a visual beep; i.e., the screen will flash instead.


    Graphics
      Lock Graphics
      To Graphics

   The Graphics Menu

This menu has two commands, the second is self-explanatory in that it does
exactly what it says, it puts you on the graphics screen (recall that we already
said graphics is  exhibited on a second, independent window or screen). If this
screen is not already open then this command causes the screen to be opened. It
then switches you to that screen. The first command is the only one which
requires some explanation, after all, what does it mean to    Lock Graphics .

To understand this you have to know that VLT supports a set of special
characters and escape sequences which the mainframe can send in order to switch
you to the graphics screen for subsequent output. It supports a second set of
sequences which switch you back to the text screen. Unfortunately, if you are on
a noisy line, or if you are logged on to the IBM and leave your terminal for a
long time, then it is not unlikely that in disconnecting you the mainframe will
send some kind of garbage which will throw you onto the graphics screen. To
prevent this from happening by accident all you have to do is select the
Lock Graphics  option. In that case VLT disables the escape sequence which
throws you onto the graphics screen.

This completes our discussion the menu options associated with the text screen.
Now we turn to a discussion of the menu options which are associated with the
graphics screen.



  Menus Associated With the Graphics Screen

When you are on the graphics screen and hold down the right mouse button the
menu bar appears and on it you will find displayed the names of the five
menus

     Image    Zoom/Pan   Cursor  Screen   Control

In this section of the manual we will provide a very non-technical discussion of
the items appearing in each of the menus. A more complete discussion of the
technical details of exactly what kind of Tektronix emulation is being provided
and how it differs from emulations available on other terminals appears in
Appendix II. A programmer's manual for the Tektronix emulation is given in
Appendix III.


    Image
       Save to Current File
       Save to New
       Load from Archive
       Quit Archive


   The Image Menu

The selections in the Image  menu are concerned with saving vector graphics
files (which are coming from the mainframe) either to a archive file you have
already chosen, called the Current File, or to a new archive file of your
choice. Old files which have been saved to an archive can be displayed on the
graphics screen without losing the current display which has just been sent from
the mainframe. To return to the current file all you have to do is Quit the
archive file. Keyboard alternatives, when they exist, are shown to the right of
the menu item, and the    Save to New  and    Load From Archive  commands
use Charlie Heath's file requester to get the name of the file you wish to save
or load. If you select one of these items and there is no current file a message
window will open and let you know this fact.

    Zoom/Pan
      Select Zoom Area
      Select Pan Area
      Reset Zoom/Pan

   The Zoom/Pan Menu

  Select Zoom Area

VLT supports true zoom.

This means that one can magnify any section of a picture which has been
downloaded from the mainframe to an arbitrary degree without loss of the
resolution which was present in the original picture. To select the area to be
magnified  simply position the cursor at the upper left hand corner of the
region of interest, hold down the left mouse button and then move the mouse to
drag out a rectangle which will define the zoom area. When you have
satisfactorily outlined the area you are interested in viewing at greater
magnification simply release the left mouse button.

  Select Pan Area  Once you have zoomed in on a region of a picture you
might want to slide the viewport over so as to reveal another region of the
magnified picture without having to first redraw the original and then zoom in
on a new region. To do this you select the pan option. Having done this you hold
down the left mouse button and move the mouse in the direction in which you wish
to have the display region move. A frame will appear as you do this in order to
show you how your new display region will be positioned relative to the picture
currently being displayed on the screen. Panning is only possible if you are
looking at a picture which has already been zoomed (with the exception that
VLT will allow you to pan upwards a limited amount).

  Reset Zoom/Pan  does just what it says, it causes the original,
unzoomed picture to be displayed upon the screen.

       Cursor
          Switch Graphic Cursor On
          Switch Graphic Cursor Off
          Display Cross-Hair Only
          Display Cross-Hair + XY

   The Cursor Menu

This menu provides commands for turning cross hairs on and off and controlling
the information which is displayed upon the screen when the cross hairs are
turned on. Under ordinary circumstances only the last menu option is meant to be
used, the other features are really meant to be turned on and off under the
control of the mainframe. Sometimes, however, it is convenient when viewing a
graph to be able to display the cross hairs in order to make it simpler to read
the coordinates of a point off a graph; in that case these menu options provide
the user with the ability to toggle the graphics cross hairs on and off under
local control. If you select the last option then when the cross hairs are
displayed the coordinates of the cross hairs relative to the bottom left hand
corner of the screen are also displayed (in Tektronix pixel coordinates). This
feature is useful if you are using the cross hairs to interact with a mainframe
graphics program and want to position the cursor very accurately.

      Screen
         Clear Screen
         Screen to Back
         Select Screen Type
         Select No. of Colors
         Select Colors
         Close Screen

     The Screen Menu

The entries in this menu are self explanatory given the discussion of the
analagous menu options for the text screen.    Clear Screen  allows you to
erase the screen under local control.    Screen To Back  moves the VLT
screens to the back of all other screens which are open (think of these screens
as being arranged like a stack of cards).    Select Screen Type  lets you
change the screen from a Workbench Screen to a Custom Screen and back.
Select No. of Colors  lets you choose the number of colors which can be used to
display graphics on a Custom Screen (nothing can be done about the fact that the
Workbench screen only displays four colors). Unlike the case of the text screen,
the graphics screen can display up to 16 colors out of a palette of 4096. These
colors are selected by bringing up the same palette gadget that you became
familiar with for changing the colors of the text screen. If you are finished
displaying graphics and wish to recover the memory being used to keep the
graphics screen open you simply select the    Close Screen  option. If, at any
later time, you wish to display more graphics, then this screen will
automatically reopen itself if there is enough memory available.


     Control
       Return to Alpha--Numeric
       Set Preferences


   The Control Menu

This menu has only two options. The first provides a way of manually getting
back to the text screen from the graphics screen. The second menu brings up a
requester which allows you to choose the kind of graphics terminal emulation
which you get. This requester is different from the others, however it works in
the same way. Some items are just names of different options, simply click on
the one you wish to select. Other items are string gadgets which contain
numerical information which you can set; in order to modify an entry click on it
and then type what you want into the space provided. Use the backspace and
delete key to erase material already present. After you have set up all of your
preferences simply click on the    Save  gadget and these settings,    along
with all of your color settings  , will be saved to a file in your    s:
directory called    s:TekPrefs.dat .

The first option which you can select is whether or not the graphics screen
emulates a true Tektronix 4010/4014 terminal, or whether it provides an extended
emulation. If you select the extended emulation then the graphics mode will
accept additional escape sequences which allow the mainframe to perform many of
the functions performed by an Ambassador GXL; for example, toggling you between
the graphics and text screens automatically. The details of the extra escape
sequences recognized in Extended mode are provided in Appendix III. If you are
using the terminal at SLAC and have no reason to dig into technical details then
simply select the    Extended  option. Note, the    Amiga   option is not
currently implemented and cannot be selected. In fact, we are not really sure
what extra features it will support.

The next option which you can set has to do with how cursor reports are returned
to the mainframe. Suppose for example, that a mainframe application has brought
up the cross hairs (i.e., the graphics cursor) and you are expected to position
the cursor over some point on the screen and then you are supposed to hit a key.
The mode that you are currently in is called the graphics input mode and the
report options have to do with what information is sent back to the mainframe
after you hit a key. In general this information consists of the key which you
hit, the location of the cursor on the screen (i.e., its XY coordinates) and
then some kind of end of report sequence to tell the mainframe that you have
completed the operation. The default is to terminate a report by sending a
carriage return, the other two options are discussed in Appendix II. If you are
at SLAC it is recommended that you select the default option.

In addition to the question of how one should terminate a report to the
mainframe there is the question of what type of report should be sent. This
option controls whether or not the XY coordinates are taken to run over the
range  0 to 1024, or 0 to 4096. If you select    4010/14 Report  then the
cursor coordinates will be sent assuming that the screen has 1024 times 1024
pixels; if the extended report is chosen the the cursor location will be sent as
if the screen display consisted of 4096 times 4096 pixels. The default
option, which is the one to be used at SLAC, is the    4010/14 Report .

The freedom to adjust the display size allows you to select the horizontal and
vertical extent of the display region on the screen. Adjusting these values
allows you to correct for faulty aspect ratios in some plots, and also allows
you to set up a sort of global magnification. In general the defaults which are
set in the    s:TekPrefs.dat  file provided are reasonable values to start
with. You can play around with these and see if you prefer values which are
slightly different. If you have a very different screen size, you may wish to
delete TekPrefs.dat entirely and have VLT recalculate the best values for you.

The incremental step options has to do with how far the cursor moves each time
it receive a ``move one pixel'' command from the mainframe to change location.
Ordinarily this should be set at 1/4096.

Finally, there is the question of the mouse character. The reason this is
included is to allow the user to program the left mouse button to send a single
letter when clicked. Thus, the user can initiate a cursor report without having
to hit the keyboard. If, however, a letter other than the default set in this
option is needed then keyboard input will be required.

  Saving All Settings  All graphics screen settings will be saved to the
file    s:TekPrefs.dat  when you click on the    Save  gadget. Having done
this, these settings then become the default settings which will be used
whenever the graphics screen is opened.

      To temporarily change the settings you
should click on the    Use  gadget. If you wish to forget the whole thing
click on the    Cancel   gadget. To start over from previously saved settings
click on the    Reset  gadget. Clicking twice on the    Reset   gadget
returns the graphics screen to VLT 's ``factory'' settings.




         Writing Scripts

   What Are Scripts?

  Very often people wish to program the terminal program to carry on some boring
or repetitive task without demanding their personal attention. For example, a
person who often logs on to the same mainframe might want to automate his logon
procedure up to the point where he types in his password (never put your
password into the program as this makes it trivial for anyone using your machine
to discover what your password is). To make this possible many terminal programs
support a macro (or script) language. VLT has its own fairly sophisticated
scripting language which can be run even without AREXX in your machine and which
will allow you to carry out simple tasks of this type. Using this macro
capability you can write scripts which can set most of the parameters which can
be set from the menus, initiate file transfers and send strings to the
mainframe. All of this, however, is run from within the terminal program, and
while a script is running the rest of the program is essentially shut down.
Also, while the native scripting capability of VLT is fairly powerful it is
not a real programming language and it has no ability to interact with other
programs which might be running at the same time.

If, on the other hand,  AREXX are present then VLT 's native scripting
capability becomes part of a full, BASIC--like, programming language that
co-exists within the Amiga's unique multi-tasking operating system. Because of
this it is possible to write scripts that do all the aforementioned things, but
many more things are possible. For example, if one is on a bulletin board and
wishes to send mail, but one is unhappy with the editor provided there, it is a
trivial matter to set the scrolling area of the terminal to only occupy the
upper half of the screen and then to open a TxEd Plus window on the lower half
of the screen. The same script which opens this window and positions it where
you wish can also reprogram TxEd Plus' ENTER key to send the file you are
currently typing to the terminal when you have edited and checked it to your
heart's content. In fact, with only slightly more work, arrange that hitting the
ENTER key only send what you typed in since the last time you hit the ENTER key
to your current place in the file. This gives you the ability to send parts of a
note, letting the bulletin board know you are still alive, and still have a full
history of the file you have sent available. This would be an example of
modular software  at work, a concept which is being discussed for other
machines, but is alive and well on the Amiga today.

At present Amiga TeX , TxEd Plus and VLT all support this kind of
cooperative AREXX intermediated behavior. This allows you to mix and match
independent applications to your heart's content under your own control.

In this section we will first list all of the commands that VLT recognizes and
then give examples of native and AREXX script files which carry out various
useful tasks.


   Commands

We first begin by giving a table of those commands which can only be used in
startup scripts; i.e., files like    s:vlt.init  which are read when VLT
starts up. The commands which set screen colors require you to specify three
hexadecimal numbers, each of which ranges from 0 to F (the numbers 0 to 15). The
first number specifies the amount of red there is in the color you wish to
create, the second, the amount of green, and the third, the amount of blue; for
example, 000 means black, F00, bright red, 0F0, bright green, 00F, bright blue,
and FFF, white. To get a feeling for what colors you get play with the palette
selector in the    Screen  menu, since it works in exactly the same way.

  Initialization File Only Commands

           Name            Argument Values            Function

    BACkground           | (e.g. 000, FFF) |  set background color
    BOLd                 |      "          |  set bold color
    CURsor               |      "          |  set cursor color
    DEPth                |      "          |  set screen depth
    FOReground           |      "          |  set foreground color
    COL4                 |      "          |  set color 4
    COL5                 |      "          |  set color 5
    COL6                 |      "          |  set color 6
    COL7                 |      "          |  set color 7
    INTerlace            |  ON/OFF, YES/NO | interlace ON/OFF
    SCReen               |  W, C           |  Screen, Workbench/Custom
    TEK_load             |  ON/OFF, YES/NO |  Preload Tektronix screen
    WB_colors            |  ON/OFF, YES/NO |  use Workbench colors

The second set of commands are things which can only be executed from a native
VLT script (a file which is assumed to have the default extension .s.
These commands are a part of Dave Wecker's original VT100 program.
When running an AREXX script a DELay is best accomplished by calling the AmigaDOS
WAIT command. GOTO is unnecessary since AREXX scripts have very sophisticated
control structures; however, the ON and WAIT commands do not, at present, have a
nice way of being called directly from AREXX. EXIT can have no arguments, in
which case it exits the current script, or it can have the argument VLT, in
which case it exits VLT. If the argument is the name of another script file,
VLT will exit the current script and start executing the specified one.
The command RX will execute an AREXX script. This is, however, not supported
from within an AREXX script.



                       Commands Only For VLT Scripts

           Name            Argument Values            Function

    DELay               | integer (seconds)    |   delay number of seconds
    EXIT                | VLT or script file   |   exit script or VLT
    GOTo                | "labelname"          |   goto label
    ON                  | "string" "command"   |  on a 'string' do a command
    RX                  | "Rexx command string"|  do a REXX string command
    WAIT                | "string"             |   wait for a host string

The remaining commands can be executed from any AREXX or native VLT script.
The only new thing that one has to know about here is the symbol ^, which is
referred to as the keyscript introducer. The keyscript introducer is the
character which you must put in front of the name of a script file when it is
programmed into a function key in order that it recognize that this is the name
of a file to be executed. The list of commands falling into the generally
available category is given in the tables on the next two pages. There are,
however, several commands that cannot be used in the initialization file (such
as all the file transfer commands).


                   Generally Available Commands

       Name            Argument Values            Function

    APPlication      |  ON/OFF, YES/NO        |  turn app. cursor on/off
    ASCii_send       | "filename"             |  ascii send a file
    BAUd             | integer (300 - 19200)  |  set baud rate
    BEEp             | none                   |  beep
    BUFfer           | integer (512 - 2048)   |  set buffer size
    BREaktime        | integer (microseconds) |  set break time
    BTAb_shift       | ON/OFF, YES/NO         |  shift-tab sends ESC - TAB
    CAPture          | "filename"             |  capture to a file
    CD               | "new path"             |  change directory
    DOWncase         | ON/OFF, YES/NO         |  Kermit: downcase file names
    ECHo             | ON/OFF, YES/NO         |  turn echo on or off
    EMIT             | "string"               |  display line on screen
    F                | integer "string"       |  define function key
    HANdshake        | N, X, 7, W             |  Handshake with serial
                                                 port None, Xon/xoff, 7-wire,
                                                 7 + X


                     Generally Available Commands

        Name            Argument Values            Function

    HEIght_cursor    | integer (pixels)       |  set cursor height
    KERmit_flags     | S, H                   |  set kermit flags:
                                                 Send/receive, Host is server
    KEYscript_char   | hex value (e.g. 7E)    |  keyscript character
    KB               | none                   |  kermit bye (for server)
    KG               | "filename"             |  kermit get file
    KMAXPACK         | packet size            |  kermit maximum packet size
    KR               | none                   |  kermit receive file
    KS               | "filename"             |  kermit send file
    LFHelp           | ON/OFF, YES/NO         |  help key sends LF
    LOCk_graphics    | ON/OFF, YES/NO         |  no tek: lock tek screen
    LINes            | integer                |  number of lines
    MODe             | N, I, C                |  C = convert cr/lf to lf
    MOUse_to_host    | ON/OFF, YES/NO         |  send mouseclicks to host
    NUMKEYpad        | ON/OFF, YES/NO         |  turn numeric kpad on/off
    PARITY           | N, E, O, M, S          |  set parity, None, Even, Odd,
                                                 Mark, Space
    PREScroll        | integer                |  max. number of lines of
                                                 prescroll
    RENDer           |  Q, N, C               |  rendering mode: Quick,
                                                 Normal, Color
    SB               | none                   |  send a break
    SD               | integer                |  set ascii-send delay
    SEND             | "string"               |  send string to host
    SWAP_bs_del      | ON/OFF, YES/NO         |  Swap BS and DEL
    VOLume           | integer                |  set volume
    VPFkeys          | ON/OFF, YES/NO         |  screen (virtual) PF keys
    WIDth            | integer                |  number of columns
    WRAP             | ON/OFF, YES/NO         |  turn wrap on or off
    XFEr_protocol    | X, K, A                |  set transfer protocol
                                                 XMODEM, Kermit, Ascii
    XR               | "filename"             |  xmodem receive file
    XS               | "filename"             |  xmodem send file
    XMOdem_flags     | N, 1, C, 1C            |  set xmodem flags: 1 =
                                                 1K blocks, C = CRC



   A Sample Startup Script

In the belief that a good example is worth a thousand words we now present an
example of an  .init  file. If you were to put this file in your current
directory as    vlt.init  or you were to file it as    s:vlt.init  then it
would override the defaults specified in    s:VTPrefs.dat  The commands all do
the same thing that you could do by setting the menu options by hand, except for
the line    exit script.name  which causes the    .init   file to terminate
and then run a script file.

One further point which should be noted is that the character # is used to
preface a comment in an internal VLT script. Everything which appears on a
line following the character # is ignored. Also, one types ^@ before the
name of a script or AREXX file which is to be executed by a programmed function
key.

   Sample Initialization File VLT.INIT

#
#     This is a sample initialization file.
#     The settings listed here override
#     the program's defaults and also the ones read from vtprefs.dat.
#     These files may be located in the current directory and/or
#     in s:. The default directory is searched first.
#
# Transfer protocol: Ascii, Kermit, XMODEM
BAUD               2400
# Anything after required fields is ignored
BREAK              75000
# Break time in micro-seconds
B TAB_SHIFT        NO
# Set SHIFT TAB to send ESC TAB. Else just TAB.
BUFFER             2048
# 512  Input buffer size le 2048
BACKGROUND         000
# Colors are in hex RGB from 000 to FFF
BOLD               950
# Color for bold highlighting (in custom)
COL4               D00
# The RGB setting of color 4
COL5               D90
# The RGB setting of color 5 (color mode bold)
COL6               045
# The   RGB  setting of color 6
COL7               999
# The RGB setting of color 7 (color mode cursor)
CURSOR             080
# Color for cursor (in custom screen)
FOREGROUND         078
# Colors are only used on the custom screen
DOWNCASE           YES
# KERMIT should downcase host names
DEPTH              3
# number of bit planes to use (1 or 2 or 3)
ECHO               ON
# Full duplex mode in use
HEIGHT_CURSOR      1
# Cursor height
INTERLACE          ON
# ON for CUSTOM or interlaced workbench
KEYSCRIPT          7E
# Hex value for script introducer
LFHELP_KEY         NO
# Set HELP key to send LF, else send keypad ','
LINES              35
# normal le   24 interlaced le 48
MODE               IMAGE
# IMAGE or CRLF (for KERMIT transfers)
MOUSE              OFF
# Mouse events to host on or off
NUMKEY             ON
# The keypad should be numeric
PARITY             EVEN
# NONE (= 8 bit), MARK, SPACE, ODD or EVEN
RENDER            Q
# Render mode: Quick, Normal or Color
SCREEN            CUSTOM
# may be CUSTOM or WORKBENCH
SWAP              OFF
# Don't Swap the Back-space and Delete keys
TEK_LOAD         NO
# Load Tektronix screen and preferences.
VOLUME            0
# Beep Volume (0 = Visual Beep)
VPF_KEYS         ON
# PF keys on the screen off or on
WBCOLORS          NO
# ignore custom colors and use defaults
WRAP              OFF
# Auto wrap ON or OFF
LOCK_GRAPHICS     NO
# Disable Tektronix graphics
XMODEM_FL         C1
# XMODEM flags. C is CRC, 1 is 1K blocks
KERMIT_FL         S
# Kermit flags, H = host is server
XFER_PROTOCOL     X
# Transfer protocol: Ascii, Kermit, XMODEM
WIDTH             100
# Number of columns
HANDSHAKE         X
# N=none, X=Xon/Xoff, 7=7wire, w=7/XonXoff
PRESCROLL         8
# Max. number of lines of prescroll
KMAXPACK          1000
# Max. Kermit packet size
#
#    Function bindings (strings to type when any of F1 - F10 are pressed)
#   f<num>      = function key
#   f<num>+10   = shifted function key
#   f<num>+20   = ctrl-ed function key
#   f<num>+30   = alt-ed function key
#   f<num>+40   = menu items right-Amiga 1 - 0
#   f<num>+50   = screen pf gadgets
#
#    Strings are parsed at the time the corresponding function key is
#    activated. Unlike previous versions of the program, this version uses
#    standard AmigaDOS (ARP) escape conventions.  This means that the
#    byte stored in ArpBase.ESCChar is used to detect the escape values.
#
#    This defaults to the undocumented BCPL '*' character,
#    but the Set command provides users with a method for changing
#    this default.
#
#    Currently the following special characters are recognized:
#      N   -   newline
#      T   -   horizontal tab
#      V   -   vertical tab
#      B   -   backspace
#      R   -   return
#      F   -   formfeed
#      E   -   escape (ascii 27 decimal)
#      Xnn -   character representd by   hex value nn.
#
#    The above may be either upper or lower case.  If an escaped character
#    which is not one of the above is given,  it will return the character
#    value (i.e. '* A' will be replaced by the single character 'A'.
#    The sequence '* *' is replaced by the single character '*',
#    and so on.)
#
#    For sending hex codes, the * X argument may be followed by either
#    one or two hex digits, in either upper or lower case.
#
#    If the first character of the string is a script introducer (KEYSCRIPT)
#    then the string is interpreted as a script item.
#    If the next character is a @, the following string will be considered the
#    name of a script file.
#    If the file extension is .vlt or .rexx, the script name will be sent
#    to the REXX host when the key is pressed. If the extension
#    is .scp, the lines in the corresponding file will be executed as VLT
#    script commands. Otherwise, the string following the script introducer
#    will be interpreted as a VLT command.
#
#    Examples of bindings:
#
#    F 10 "* EOP"
#
#    means send <escape> O P to host upon pressing F10.
#
#    F 11 " emit 'This is a test'"
#
#    means send "This is a test" to the VLT screen upon pressing shift-F1.
#
#    F 22 "^ rx 'send this to rexx'"
#
#    means send "send this to rexx" to the REXX host as a string command upon
#    pressing ctrl-F2
#
#    F 32 "^ @dialbix.scp"
#
#    means execute the VLT script "dialbix.scp" upon pressing alt-F2.
#
#    F 44 "^ @dialwork.rexx"
#
#    means send "dialwork.rexx" to the REXX host as a command upon pressing
#    right-Amiga 4.
#
#    F 55 "^ send '* EOP'"
#
#    means send <escape> OP to the host upon clicking the F5 gadget on the
#    screen. This is equivalent to example F 10.
#
f 1       "* EOP"
# F1 gives standard VT100 PF1 sequence for VAX and IBM
f2        "* EOQ"
# F2 gives standard VT100 PF2 for VAX and IBM
f3        "* EOR"
# F3 gives standard VT100 PF3 for VAX and IBM
f4        "* E4"
# F4 gives correct VT100 PF4 for IBM should be * EOS for VAX
f5        "* E5"
# F5 gives correct PF5 for IBM, no counterpart on VAX
f6        "* E6"
# F6 gives PF6 on IBM
f7        "* E7"
# F7 gives PF7 on IBM
f8        "* E8"
# F8 gives PF8 on IBM
f9        "* E9"
# F9 gives PF9 on IBM
f10      "* E0"
# F10 gives PF10 on IBM
f11      "* E-"
# (shift)F1 gives PF11 on IBM
f12      "* E="
# (shift)F2 gives PF12 on IBM
f13     "* E!"
# (shift)F3 gives PF13 on IBM
f14      "* E@"
# (shift)F4 gives PF14 on IBM
f15      "* E#"
# (shift)F5 gives PF15 on IBM
f16      "* E$"
# (shift)F6 gives PF16 on IBM
f17      "* E%"
# (shift)F7 gives PF17 on IBM
f18      "* E^"
# (shift)F8 gives PF18 on IBM
f19      "* E&"
# (shift)F9 gives PF19 on IBM
f20      "* E* * "
# (shift)F10 gives PF20 on IBM
f21      "* E("
# (ctrl)F1 gives  PF21 on IBM
f22      "* E)"
# (ctrl)F2 gives PF22 on IBM
f23      "* E_"
# (ctrl)F3 gives PF23 on IBM
f24      "* E+"
# (ctrl)F4 gives PF24 on IBM
f...
f30     "c10"
# (ctrl)F10 sends the string "c10"
f31     "a1"
# (alt)F1 sends the string "a1"
f...
f41 &    "m1"
# (ra 1) sends the string "m1"
f...
f51     "* EOP"
# on screen function key PF1
f52     "* EOQ"
# on screen function key PF2
f53     "* EOR"
# on screen function key PF3
f54     "* EOw"
# on screen alternate way of getting PF4 on IBM
f55     "* EOx"
# alternate PF5 on IBM
f56     "* EOy"
# alternate PF6 on IBM
f57     "* EOt"
# alternate PF7 on IBM
f58     "* EOu"
# alternate PF8 on IBM
f59     "* EOv"
# alternate PF9 on IBM
f60     "* EOq"
# alternate PF10 on IBM
f61     "* EOr"
# alternate PF11 on IBM
f62     "* EOs"
# alternate PF12 on IBM
f63     "* E!"
# PF13 on IBM (same as above)
f64     "* E@"
# PF14
f65     "* E#"
# PF15
f66     "* E$"
# PF16
f67     "* E%"
# PF17
f68     "* E^"
# PF18
f69     "* E&"
# PF19
f70 &    "* E* *"
# PF20
f71 &    "* E("
# PF21
f72 &    "* E)"
# PF22
f73 &    "* E_"
 # PF23
f74 &    "* E+"
# PF24
f75 &    "* EOS"
# PA1 on IBM
f76 &    "* E* X7F"
# EOL (erase to end of line) on IBM
f77 &    "* EOn"
# INS (insert key which stays lit to show insert
mode) on IBM
f78 &    "* EOl"
# TRQ (test request, brings back last command) on
IBM
f79 &    "* R"
# RET (Carriage return)
f80 &    "* EOM"
# CLR (clear screen)
#
#   all done with init, now execute script as startup sequence
#
#    exit df1:vt100_source/dialwork.scp

The preceding script was an example of a native VLT initialization script.
Other native scripts are written in exactly the same way and can be executed
either from a preceding script, or from the    Macros  menu by choosing the
VLT script  option. In the remainder of this chapter we will be more
interested in giving examples of the way in which VLT 's AREXX interface can be
used to write much more powerful interactive scripts.

There are two sorts of AREXX scripts which can be written and they behave
slightly differently. In general, if you have an AREXX macro it will have an
extension of the form    .rexx . If you wish to send a command to VLT then
you preface it with the

   ADDRESS VLT

string, as is explained in the AREXX manual; where in this case, VLT is the name
of the message port that VLT opens when it is running. Hence if you wish an
asynchronously running AREXX macro (say running in the editor) to tell VLT to
send a string to the mainframe all you have to do is include the line

   ADDRESS VLT SEND "string"

in your AREXX macro.
In addition to the general sort of AREXX macro there are special VLT macros;
these are the ones with file extension    .vlt . If you write a macro of this
type then you never have to type

   ADDRESS VLT

because AREXX will assume that any command that it does not recognize is a VLT
command and pass it on to the program. In this case, however, any command you
wish to pass to the Amiga WSHell or CLI environment will need to be prefaced by
the command

   ADDRESS COMMAND

The next example shows how the AREXX macro rexx:Amiga_to_IBM.vlt  works.
Note, this macro first opens the special AREXX support libraries discussed
earlier so that it can call the functions    postmsg ,    getfile  and
request . The documentation for these functions is provided on the distribution
disk. It can also be found on the SLAC VM Amiga disk.

   An Example of a .vlt  Script

/* this is a test for a window which pulls stuff */
check = addlib('rexxsupport.library',0,-30)
check = addlib('rexxarplib.library',0,-30)
check = addlib('rexxmathlib.library',0,-30)

host = address()

ft = 'temp'
fm = 'a'

    msgstring =            "   This routine sends a file to    "
    msgstring = msgstring||"   the IBM mainframe.  To select   "
    msgstring = msgstring||"   a file to send simply use the   "
    msgstring = msgstring||"   file requestor up above.        "
    msgstring = msgstring||"   If you hit CANCEL the transfer  "
    msgstring = msgstring||"   terminates.  The same happens   "
    msgstring = msgstring||"   if you fail to choose anything  "
    msgstring = msgstring||"   and hit OK.                   "

    y = postmsg(326,178,msgstring,host)
done = 0
do outer = 1 until done = 1


  filerep = getfile(326,56,,,"CLICK DIRECTORY AND/OR FILE",host)
/* this checks to see that not everything is blank. */

  if filerep = '' then do
      x=postmsg()
      exit
  end

/* here we check to see that we got a file and not just a directory */

  dircheck = statef(filerep)
  dirnum = index(dircheck,"DIR")
  if dirnum ~= 0 then do
    msgstring =            "   The name of the file itself "
    msgstring = msgstring||"   should appear in the lower  "
    msgstring = msgstring||"              box.             "
    msgstring = msgstring||"                               "
    msgstring = msgstring||"           TRY AGAIN           "
    msgstring = msgstring||"     (click left mouse button) "

    y = postmsg(,,msgstring,host)
    iterate outer
  end

    x=postmsg()

    parse var filerep dir ":" filerep
    if filerep = "" then do
     filerep = dir
     dir = ":"
    end
    else dir = dir":"
    filerep = reverse(filerep)
    parse var filerep filename "/" subdir
    filename = reverse(filename)

    sendfile = dir||reverse(filerep)

    parse var filename xfn"."xft
    if xft ~= "" then ft = xft


fillstring = ""
  fillstring = fillstring||"What do you wish it to be called"
  fillstring = fillstring||"on the main frame?"
  fillstring = fillstring||"The name shown below is the default"
  fillstring = fillstring||"To assign your own name type over it"

defaultname = xfn" "ft" a"

ibmname = request(326,56,fillstring,defaultname,"Send It","Cancel",host)

if ibmname = "" then exit

if ibmname ~= defaultname then do

  parse var ibmname ifn ift ifm

  select

    when ifn  = '' then ibmname = fn" "ft" "fm
    when ifn ~= '' & ift = '' then ibmname = ifn" "ft" "fm
    when ift ~= '' & ifm = '' then ibmname = ifn" "ift" "fm
    otherwise ibmname = ifn" "ift" "ifm

  end

end
if host ~= "VLT" then x = screentofront("VLT")

if host ~= "VLT" then address VLT

       sendstring = "kermver4 receive "||ibmname" *R"
       sendstring = '"'||sendstring||'"'

        SEND "*R"
        call delay 100

        SEND "*X7"
        call delay 50

        SEND "*R"
        call delay 50
        SEND "*R"


        SEND sendstring

        call delay 100

        KS sendfile


        SEND "*R"

        call delay 50

        SEND "*R*R"

        call delay 50

        SEND "*R"

        SEND "*R"

        SEND "*N"

    done = 1

end

if host ~= "VLT" then x = screentoback("VLT")
exit

ERROR:

   say "There has been an error somewhere "
   exit 20

SYNTAX:
   say "Syntax error"
   exit 20


NOVALUE:
   say "Novalue error"
   exit 20

HALT:

   say "External Halt detected"
   exit 20

BREAK:

  say "Control C detected"
  exit 20



Finally we close with an example of an AREXX macro which is designed to work
from withing TxEd Plus and send a file to VLT if it is running. It checks to
see if VLT is around and puts up an error message and exits if it is not
around. Of course, it could equally well start it up.



/*  this file will let you use TxEd Plus as a terminal command line * /
/*  if you assign the enter key to execute the file asend.txed       * /
/*  to do this put the line -- MACRO E asend -- in your startup.txed * /

sendfile = "vd0:asciitempfile"

OPTIONS results
lastline = 0
lastcol = 0

  STATUS R XXXXXXXXXXXXX&
  INSERT * X20                      /*  insert an extra space for cut/p*e * /
  STATUS R                          /*  find out where the cursor is * /
  parse var result newline  newcol  /*  parse result to line and column * /
  JUMP lastline lastcol             /*  go to lastline first column */
  MARK                              /*  start a cut/p*e block * /
  JUMP newline newcol+1             /*  mark the block * /
  COPY MX                           /*  cut the block to a temp. buffer * /
  lastline = newline
  lastcol = newcol+1

  STATUS MX                         /*  get what is in the X buffer */
  string = result
  x = open("ATEMP",sendfile,"W")    /*  open a file to send * /
  x = writeln("ATEMP",string)       /*  put the string in the file * /
  call close("ATEMP")               /*  close the file * /
  address VLT                       /*  send all remaining commands to VLTC */
  ASCII_SEND sendfile               /*  send the file * /
  exit


   Programming Function Keys

All of the commands which are generally accessible from an AREXX exec
can also be executed from any one of the 80 programmable function
keys.  See the .init  script for an example of this sort of thing.



         Appendix I

   Introduction

VLT recognizes a subset of the standard VT100-style escape sequences when in
VT100 mode. Some of them, however, are handled in a somewhat different way. In
addition, there are some additional sequences that a regular VT100 does not
recognize. The differences and additions are listed in this appendix.

   Tektronix-emulation related sequences

The following two sequences switch between VT100 and Tektronix
emulation modes.

  XXXXXXXXXXX

  ESC   FF      Switches to Tektronix emulation and clears the Tektronix
                      screen.
  CSI   38      Switches to Tektronix emulation without clearing the
                      Tektronix screen.
  CSI   38      Switches back to VT100 emulation.

Here,  CSI  is the sequence  ESC  [ .


In Extended emulation mode some single character sequences are recognized that
switch to Tektronix emulation:  US ,  GS , and  FS . A sequence
that switches to VT100 mode is  CAN . For more details see Appendix III.

One other graphics related sequence is recognized:  ESC #!0 . This is a
request for a report on which emulation mode VLT is currently in. The response
to this report is a sequence of 6 characters: %!001 CR  if the current mode
is VT100, and %!000 CR  if the current mode is Tektronix.

   Differences for standard VT100 sequences

In the case of a regular VT100, the sequences  CSI 1p and CSI 0p switch
one of the keyboard LEDs on and off.

Since the Amiga does not have a set of keyboard LEDs, this function switches
the highlighting status of the  INS  gadget on the screen on or off, if
the gadgets are currently displayed.

The sequences  CSI  P_0; ...; P_n m are used on VT100's to change the
current mode of graphic rendition.  However, if the
Color  option of the  Rendition  menu item is selected, the
various renditions will be mapped to the colors 1 through 5 of the
current palette of the screen.

It is recommended that a 3-bitplane custom screen be used in this mode,
although this works with a Workbench window as well (though some color
information is lost).

The assignments are as follows:

  P_n       Normal operation:         Color mode operation:

   0     Normal attributes                 Use color 1
   4     Underlined                        Use color 2
   1     Bold                              Use color 3
   7     Reverse video                     Use color 4
   5     Italic                            Use color 5

In addition, some ANSI style color sequences are recognized, see section 3.



   Additional sequences

Some additional sequences of the type  CSI  P_0; ...; P_n  P_m are recognized.
They affect only the color selection for text display and work  only if the
Color  option of the  Rendition  menu item is selected.

The following values of P_n are recognized:

  P_n           Color mode operation effect:

  30            Change to color 0 (background)
  31            Change to color 1
  32            Change to color 2
  33            Change to color 3
  34            Change to color 4
  35            Change to color 5
  36            Change to color 6
  37            Change to color 7
  40            Set normal rendition, color 1, restore saved mode, erase screen
  41            Set normal rendition, color 1, save mode, set color mode on

The latter two sequences allow one to use the terminal normally in  Quick
rendition mode, but to temporarily switch to  Color rendition and later
back to the saved settings.

These two sequences are not ANSI compatible.

Finally, there is an escape sequence to set the number of lines on
the screen.

For compatibility reasons with other terminals, this sequence has the
form  CSI P_1; P_2; P_; P_4 P, where only P_4 is significant: it is
the number of lines that the screen should be set to.

The screen contents are erased by this process.








         Appendix II
 -30pt
          Tektronix Emulation

   Introduction
This appendix briefly describes the Tektronix  4010/14 Graphics Emulator
implemen-ted in VLT and serves as a User's Guide.  The current implementation
features almost full Tektronix 4010/14 emulation as found, for example, in
the DEC VT240 terminal.

In addition to alpha and vector graphics modes, also point-plot
and incremental plot modes are supported as well as an extended graphics mode.
Vectors can be light or dark. Light vectors can have normal or high intensity
and a full set of patterns is provided.

The Emulator supports the extended variable-length vector-mode protocol of
the Tektronix 4014 and 4100 series of terminals for a maximum resolution of
4096 times 4096 pixels.  This version includes support for color: the number of
colors may be set through a menu option, the colors may be adjusted using a
requester, and Tektronix 4105 style escape sequences for host-control of
colors and line styles are recognized.

The Emulator has a fully functional Graphic INput (GIN) mode and the cross-
hair cursor can be operated with the mouse or the arrow keys.  Optionally,
the current position of the graphic cursor is displayed numerically.
Other options for GIN mode include the standard end-of-report sequences and the
extended (5 byte) report of the Tektronix 4100 series of terminals.
These settings, as well as the character sent as part of the GIN report when
the mouse select button is pressed may be entered through the  Preferences
requester.

Pictures are captured and can be saved to  disk and reviewed later.  The zoom
and pan features allow enlargement of any part of the screen while retaining
the full resolution inherent to the graphics primitives sent to the
terminal.

This appendix, the User's Manual, describes the operation of the Graphics
Emulator from the user's point of view. Descriptions are given of all menu
options and requesters as well as the various modes of operation.

The next Appendix contains a Programmer's Manual that lists all command
sequences that can be given from the host and to which the Graphics
Emulator will respond.


   VLT's modes

VLT has two ``supermodes'': Alphanumeric and Graphic. In Alphanumeric
supermode the program behaves as a VT100 ASCII terminal, in Graphic
supermode the program emulates a Tektronix graphics terminal. Each
supermode has a separate associated window such that the display in one
does not affect the text in the other. When the terminal is in
Alphanumeric supermode, the window usually contains text and the
program responds to standard VT100 escape sequences.
The Alphanumeric supermode (VT100 mode) is described elsewhere.
In Graphic supermode the associated window usually contains graphical
displays, and the program responds to Tektronix 4010/14 control sequences.

The terminal supermode can be set to  Alpha-Numeric  or  Graphic
by selecting the appropriate item from the  Control  and Graphics
menus respectively. On start-up, the terminal supermode is Alphanumeric.
One may also switch between supermodes from the keyboard by pressing the
right Amiga key (RA) and the letter F simultaneously (in the following
this will be abbreviated as RA-F).

In Graphic supermode the program can be in any of five modes: alpha
mode, vector mode, point-plot mode, incremental plot mode and Graphic
INput (GIN) mode.
In alpha mode the program behaves as a dumb ASCII terminal and allows the
display of alphanumeric text. (Notice, that this mode is not the same as
the VT100 Alphanumeric supermode!).

In vector mode the program interprets incoming data from the serial
port as  x,y  coordinates of vectors and moves the ``pen'' to the
location x, y (when the pen is up) or draws a line from the current
position to x, y (when the pen is down). Point-plot mode (sometimes
called marker mode) operates the same as vector mode, with the
exception that all incoming  x,y  coordinates are marked on the
screen by a dot.

In incremental plot mode incoming data are interpreted
as single pixel movements of the pen in any of the 8 possible
directions.  A line is drawn or continued if the pen is currently down
and a move is executed if the pen is currently up.

In GIN mode, a graphic cursor (cross hair) is displayed and a bypass
mode is entered: all keyboard keys are intercepted by the program.
During  GIN mode the graphic cursor can be moved with the mouse or the
arrow keys. GIN mode can only be exited by typing an alphanumeric
character or by pressing the select button of the mouse.

A report is then sent to the host consisting of the character that was
typed (or, in case the left mouse button was pressed, its currently selected
character) and the current  x,y  position of the graphic cursor,
followed by an end-of-report sequence.

For more information on these modes and the control and escape
sequences that need to be sent from the host, see the Programmer's
Manual. The rest of this manual describes the menus and their function.
All menu options can be selected from the menu bar of the Graphics
Window.

In the following sections, the menus and requesters of the Graphics
Window will be discussed.

   The Image menu

Incoming data are interpreted as Tektronix 4010/14 control sequences
and normally stored in a vector format as a temporary binary file on the ram:
disk. If you would prefer the file to go somewhere else, you may want
to assign the logical name TekStore: to a directory destination on your floppy
or hard disk. This is useful if you have a limited amount of memory.
Once a picture is displayed, it can be copied to a more permanent
file on disk by selecting the  Save To New File  option from the
 Image  menu. A file requester will appear, to allow one to specify
the file name of the file to be created.

One may overwrite this file with another image by selecting the
Save To Current File  option. This option may be abbreviated via
the keyboard as RA-S.

In order to review pictures that were previously recorded to disk
select the  Load From Archive  menu option or press RA-L.
A requester will appear for the file name of the file to be viewed.
The picture will then be displayed; of course, the zoom and pan feature of
the Graphics Emulator can be used (see section 2).
The last picture that was captured before loading from the archive is still
available,  and will be redisplayed by selecting  Quit Archive  or pressing
RA-Q. This option must also be used to resume normal operation as a
Tektronix terminal emulator.

Pictures are stored in an internal compressed format that preserves the
vector information of the original image.

To facilitate transfer of such pictures to other computers, only 7 bits
are used of each byte in the file, leaving the eighth bit for parity
information where such is needed.

   The Zoom/Pan menu

To zoom in on a particular portion of the screen, select the  Select
Zoom Area  item from the  Zoom/Pan  menu or press RA-Z.  Then move
the mouse to a corner of the part of the screen to be enlarged, press
the left mouse button and move the mouse to the corner diagonally
opposite the first, while keeping the left mouse button depressed.
During this operation a box indicating the selected part of the screen
will be displayed.  When you have finished the selection, release the
left mouse button, and the image will be rescaled such that the
selected part will fill the screen.  Since the proper aspect ratio will
be preserved, a somewhat larger part of the image may be displayed than
was selected. Especially for images with considerable detail the
redrawing process may take a few seconds.

The screen will flash when the redrawing process is completed.
The zooming process may be repeated recursively, going to finer and finer
detail.  Obviously, the resolution that can be obtained depends on the
resolution with which the original data were drawn by the host, and is in
any case never better than 4096 pixels vertically and 4096 pixels horizontally.
Notice, that the Select Zoom Area  option can be activated even when no
image is currently present.

Once the zoom feature has taken effect, one may wish to slide the
viewpoint to an adjacent part of the picture.  This is called `panning'.
Select the  Select Pan Area  option or press RA-P to accomplish
this. Then move the mouse to a point away from the direction you want
to pan to, press the left mouse button and move the mouse in the
direction you want to pan to while keeping the left mouse button
depressed. During this operation a box indicating the new `window
position' will be displayed.  When you have selected the new area to be
displayed, release the left mouse button and the image will be
redisplayed at that position. This operation may take a few seconds
since the entire picture needs to be redrawn.  The screen will flash
when the redrawing process is completed.  One may pan repeatedly, or
alternate panning and zooming operations.  In the un-zoomed state, a
780 times 1024 (or 3120 times 4096) pixel area will normally be
visible. Panning upwards will allow you to see the part of the screen
that is usually obscured.

To reset the zoom/pan feature to display the full image, select the
Reset Zoom/Pan  item or press RA-R.

   The Cursor menu

Normally, the graphic cursor is only displayed when the host sends the
enter-GIN-mode command.  It should almost never be necessary to enter
Graphic INput (GIN) mode from the terminal, but the possibility is
provided as a menu option.   This option should be used with care,
however, since it alters the behaviour of the program considerably.

To enter GIN mode from the terminal, select the  Switch Graphic
Cursor On  option from the  Cursor  menu.  To exit it in a way that
is transparent to the host, select the  Switch Graphic Cursor Off
item.

If during GIN mode any alphanumeric key is pressed on the
keyboard, that character is sent to the host along with a GIN report.
During GIN mode the graphic cursor (cross hair) can be moved using
either the mouse, or the arrow keys on the keyboard.

When the arrow keys are used in combination with the shift key, the graphic
cursor moves with coarse steps, otherwise the step size is one (Amiga) pixel.
Notice, that the mouse has priority over the keypad: if the keypad is
used, any subsequent movement of the mouse will cause the graphic
cursor to jump back to mouse control.

The current position of the graphic cursor can be displayed numerically
in the top left hand corner of the screen by selecting the  Display
Cross Hair + XY  item of the  Cursor  menu or by pressing RA-N.
Numeric display is turned off by selecting the  Display Cross Hair
Only  item or pressing RA-H.  Together with the possibility of turning
GIN mode on and off transparently to the host, this option can be used
to measure the size of objects on the screen in the coordinates of the
original picture (either 1024  times  1024 or 4096  times  4096
pixels, see also the section on    reports to the host ).

The default settings for this menu are  Switch Graphic Cursor Off
and  Display Cross Hair Only .

   The Screen Menu

The  Screen  menu contains several controls to select the attributes
of the Tektronix Graphics screen and window.

The  Clear Screen  option will erase any text and graphics currently
being displayed. This option can also be invoked by pressing RA-C.

The entire VT100/Tektronix emulator can be moved behind other
applications by selecting the  Screen To Back  option (RA-J).
Note that you can only resume the terminal session by
moving the screens back to the front, either using something like
FunKeys (from MicroSmiths) or by pressing the left Amiga key together
with the N or M keys. Make sure you return to the currently active
window, be it Graphics or Alphanumeric.

The Tektronix window may be on a custom screen or on the Workbench,
selectable through the sub-items  Custom Screen  and  Workbench
of the  Select Screen Type  option.

In case the current screen is a custom screen, it may be selected to be
Interlaced  or  Non-Interlaced . If the screen is a Workbench screen
the interlace setting of the Workbench is used.

The number of colors to be used for the screen may be selected through
sub-items of the  Select No. Of Colors  item. Either 2, 4, 8 or 16
colors may be selected.

Notice, that drawing speed decreases noticably with 16 colors. When the
Graphics window is on the Workbench, only 4 colors are available and
selecting other settings will have no effect.

The colors may be adjusted using a color requester that appears when
the  Select Colors  item is selected. Any color can be modified by
clicking on the gadget of that color in the color requester and sliding
the three color sliders (Red, Green and Blue) until the desired color
is reached.

When all colors have been adjusted, clicking the  OK gadget will cause
these colors to remain in effect while exiting the color requester.
Clicking on the  Reset  gadget will cause the original colors to reappear.
The  Cancel  gadget has the same effect as  Reset , but will also exit
the color requester. Note, that one cannot change colors if the Graphics
window is on the Workbench.

The graphics window and/or screen may be closed entirely (to save memory, for
example) by selecting the  Close Screen  option.

All screen attributes may be saved to disk by selecting the  Save
gadget in the  Preferences  requester.

   The Control Menu

The  Control  menu contains two options. To return to the Alphanumeric screen,
select the  Return To Alpha-Numeric  option or press RA-F.

Various options associated with the Tektronix emulation can be selected
from the  Preferences  requester that will appear when the  Set
Preferences  option is selected. This requester is described in section
6.

   The Preferences Requester

When the  Set Preferences  menu option is selected from the
Control  menu, a requester will appear on the screen allowing the
user to set several default options. These settings can be saved to a
file, and will be automatically loaded on the next invocation of the
communications program. The requester is divided in several areas, each
with several selectable gadgets. The possible settings are described in
the following sub-sections.

In order to determine which options work best with the application you
are running on the host, consult your local system manager or use the
method of trial and error.

    Emulation Options

In Graphic supermode the program conforms as closely as possible to the
Tektronix 4010/14 standard by selecting the  Plain 4010/14  gadget
of the  Emulation Options  area. In this case, the host can send
only three particular escape sequences to switch the terminal between
Graphic and Alphanumeric supermodes, and dark vectors are not
supported. Also, a carriage return character sent from the host causes
escape from vector mode to alpha mode, whereas in Extended mode it is
ignored.

If the  Extended  gadget is selected, some graphics control
sequences are recognized both in Alphanumeric supermode and in Graphic
supermode, allowing a more flexible switching between the two
supermodes. Also, some four-byte escape sequences are recognized while
in graphic mode that allow the support of a.o. dark vectors and color.
This is the default and recommended mode of operation, unless your
system generates control sequences in Alphanumeric mode that cause
interference.

The gadget labeled  Amiga  is not currently implemented and is
disabled.

    Cursor Report Options

In Graphic INput (GIN) mode, the graphic cursor is displayed. After
moving the graphic cursor to the desired position, GIN mode is
terminated by pressing a key on the keyboard or the left mouse button.
A GIN report is then sent to the host consisting of the character that
was entered (or a selectable character in case the left mouse button
was pressed), the current  x,y  coordinates of the graphic cursor,
and the end-of-report sequence that is currently selected.

The  Cursor Report Options  area allows various properties of the
GIN report to be set. The GIN report can be terminated in three
different ways: these are what in Tektronix terminology are called the
`strappable options'. By default, GIN reports are terminated by a
 CR  character (the ASCII character for Carriage Return, decimal 13
or  ctrl  M), accessible by selecting the  End with CR  gadget.
GIN reports are terminated by a sequence of  CR  and  EOT  (the
ASCII character signifying End Of Tape, decimal 4, or  ctrl  D)
characters when the  End with CR/EOT  gadget is selected. GIN
reports are not terminated at all when the  Use No Ending  gadget is
selected.

The Graphics Emulator supports some Tektronix 4100 series
characteristics. One of them is the capability of sending extended (5
byte) GIN reports. This option is selected using the  Use Extended
Report  gadget of the  Cursor Report Options  area. The default is,
however, the standard (4 byte) GIN report expected by Tektronix 4010/14
compatible application programs running on your host. If the  Use
Extended Report  gadget is selected, the numerical graphic cursor
display (see section 3) will use a 4096 by 4096 pixel coordinate
system, otherwise the coordinate system will default to 1024 by 1024
pixels.

    Incremental Mode Options

Incremental Mode is the graphics mode in which incoming data are
interpreted as single-pixel movements in any of the 8 possible
directions. Since this Graphics Emulator supports both 1024  times
1024 and 4096  times  4096 pixel resolutions, the step size for
single-pixel movement needs to be selectable. If the application you
are using on the host sends data assuming a standard Tektronix 4010/14
compatible terminal, select the  Step = 1/1024  gadget from the
Incremental Mode Options  area, otherwise select the  Step =
1/4096  gadget (default).

    Adjust Display Size

The  Adjust Display Size  area allows you to change the horizontal
and vertical extent of the display area used for Tektronix graphics.
This is mainly useful to adjust the display size to other parameters of
your system, or to correct a faulty aspect ratio.

The number for the horizontal size corresponds to the number of Amiga
pixels the Emulator will use for the horizontal extent of the Tektronix
screen. The number for the vertical size corresponds to the number of
pixels used on the Amiga for the vertical extent. The number is
internally multiplied by 2 in case you use an interlaced display and
the value that appears in the requester is therefore independent of
interlace.

Notice, that if the file  TekPrefs.dat  cannot be found either in
the system's s: directory nor in the current default directory, these
numbers will be set to the ones currently in effect for the screen (see
also the section on    reports to the host ).

    Mouse Character

The character sent as part of the GIN report when the left mouse button
is pressed can be chosen by selecting the  Mouse Character  gadget
and typing the desired character. The default character is the
 ESC  character (the ASCII Escape character, decimal 27, or
 ctrl  [).

    Reset, Cancel, Use, Save

After changing the settings, you can use them and return to the
Emulator by selecting the  Use  gadget. You can also save the
current set of preferences by selecting the  Save  gadget: the
preferences will be saved to a file called  TekPrefs.dat , which
will be saved either in the current default directory (if no such file
exists yet, or if a  TekPrefs.dat
 is already present
in that directory) or in the s: directory (if a  TekPrefs.dat  file is found
there, but not in the current default directory).

If you decide you don't like the preferences you have just set, you can
return to the Emulator with the old preferences by selecting the
 Cancel  gadget. If you want to change the preferences but want to
start over from the previously saved ones, you can click on the
 Reset  gadget. Clicking on the  Reset  gadget a second time
causes the preferences to be reset to the `factory' settings.
Subsequent selections of the  Reset  gadget toggle between the last
saved and the factory settings.

    The current version number

The current version number of the graphics package can be determined by
displaying the menu bar using the right mouse button. The only menu is
the  Version  menu. It contains the version number.




         Appendix III
         Tektronix Programmer's Manual

   Introduction

This appendix describes the command sequences that the Tektronix
4010/14 Graphics Emulator will respond to when they are received from
the host. In the first section the sequences are described that change
the supermode. The following sections describe the sequences that are
recognized in alpha mode, vector and point-plot mode, incremental plot
mode and GIN mode. A section follows describing the various reports to
the host. The manual ends with a description of escape sequences
recognized when  Extended  emulation is selected from the
 Emulation Options  area of the  Preferences  requester.

In the following sections most control characters will be referred to
by their ASCII name. Therefore, a table of these control characters and
their numerical equivalents is appended.

   Sequences that change supermode

When  Plain 4010/14  is selected from the  Emulation Options
area of the  Preferences  requester, there are only three escape
sequences that can change the supermode. Two of them are:

 o CSI ?38h to enter the Graphic supermode, and
 o CSI ?38l to exit Graphic supermode to Alphanumeric supermode.

Here, the sequence  CSI  is a control sequence introducer, in this
case  ESC  [ .

The third escape sequence is  ESC   FF . This sequence is generally used
in Graphic supermode to erase the contents of the graphics window. When
this sequence is encountered in Alphanumeric supermode, the supermode
is changed to Graphic and the graphics window is cleared.

When  Extended  is selected from the  Emulation Options  area,
several additional control characters will change the supermode on
reception from the host. A list follows:

  CAN   Exit Graphic, enter Alphanumeric supermode.
            (Only recognized in alpha mode).
  FS    Enter Graphic supermode in point-plot mode.
  GS    Enter Graphic supermode in vector mode.
  RS    Enter Graphic supermode in incremental plot mode.
  US    Enter Graphic supermode in alpha mode.

  In addition, the sequence  ESC "0g causes exit to Alphanumeric
supermode, as well as the Tektronix 4105 sequence  ESC %!1.


For a description of each of the Graphic modes see  also Appendix II.



    Alpha mode

Once the Graphics Emulator is in alpha mode it will print incoming
printable characters to the graphics window.  If the screen is
interlaced, a 74 column by 35 line format will be used.  If the screen
is not interlaced only 24 lines can be displayed.

The Emulator faithfully mimics the two-column mode of 4010/14 compatible
terminals:

when the bottom of the screen is reached, the left margin is changed to
the center of the screen and printout resumes at the top of the screen
obeying the new margin.  When a line extends beyond the virtual graphics
screen it is wrapped around to the next line.

In addition to the printable characters, the following control
characters and escape sequences are recognized.

  ESC             Introduce escape sequence.
  ESC NUL         Same as  ESC .
  ESC ESC         Same as  ESC .
  ESC ENQ         Set bypass and return terminal
  BEL             Ring bell (flash screen).
  ESC BEL         Ring bell (flash screen).
  BS              Move one space left.
  ESC BS          Move one space left.
  HT              Move right to next tab stop.
  ESC HT          Move right to next tab stop.
  LF              Move one line down and return to left margin.
  ESC LF          Same as  ESC .
  CR              Move to left margin.
  ESC CR          Same as  ESC .
  VT              Move one line up.
  ESC VT          Move one line up.
  ESC FF          Erase and home.
  ESC ETB         Make copy
  ESC CAN         Set bypass condition.
  ESC SUB         Set GIN mode and bypass condition.
  FS              Set point-plot mode.
  ESC FS          Set point-plot mode.
  GS              Set vector mode
  ESC GS          Set vector mode
  RS              Set incremental plot mode.
  ESC RS          Set incremental plot mode.
  SP              Move one space right.
  DEL             Same as  BS .
  ESC DEL         Same as  ESC .
  ESC  8          Select largest character size
  ESC  9          Select large character size
  ESC  :          Select small character size
  ESC  ;          Select smallest charactersize
  ESC  0          Same as  ESC  8
  ESC  1          Same as  ESC  9
  ESC  2          Same as  ESC  :
  ESC  3          Same as  ESC  ;


  Notes:
   1.   For a description of the report to the host see the section
            on reports to the host.
   2.   These sequences are not currently implemented.
   3.   After vector mode is entered, a move will be executed to
        the vector that follows.   All subsequent vectors will be drawn.

   Vector and point-plot (marker) mode

In both vector and point-plot mode, the Graphics Emulator will interpret
incoming printable characters as  x,y  coordinates.  After entering vector
mode, the ``pen'' moves to the first vector encountered (the pen is ``up'').
All subsequent vector are drawn (with pen ``down'').

In the case of point-plot mode all vectors are marked with a dot.

Before discussing the encoding scheme of  x,y  pairs, it should be
noted that the Graphics Emulator works internally with a 4096  times
4096 pixel coordinate system as required for the Tektronix 4100 series
of graphics terminals. The following protocol for transfer of  x,y
coordinates is, however, completely backwards compatible with the older
4000 series with their internal coordinate system of 1024  times  1024
pixels: when the application running on the host assumes a 4000 series
terminal, the Graphics Emulator simply puts the lowest order two bits
of each coordinate to zero.

The encoding scheme of  x,y  pairs is syntactically described by:

  x,y = [ HiY ] [[ Extra ]  LoY  [ HiX ]] LoX

  Each item enclosed in on the right hand side represents an ASCII character:

   HiY        Bit 0 through 4: most significant 5 bits ofy coordinate.
              Bit 5 and 6: ``01'' (Tag bits).
              Bit 7: parity.
   Extra      Bit 0 and 1: least significant 2 bits of x coordinate.
              Bit 2 and 3: least significant 2 bits of y coordinate.
              Bit 4: unused.
              Bit 5 and 6: ``11'' (Tag bits).
              Bit 7: parity.
   LoY        Bit 0 through 4: intermediate 5 bits of y coordinate.
              Bit 5 and 6: ``11'' (Tag bits).
              Bit 7: parity.
   HiX        Bit 0 through 4: most significant 5 bits of x coordinate.
              Bit 5 and 6: ``01'' (Tag bits).
              Bit 7: parity.
   LoX        Bit 0 through 4: intermediate 5 bits of x coordinate.
              Bit 5 and 6: ``10'' (Tag bits).
              Bit 7: parity.

  In the syntactical expression above, an item enclosed in [ ]
may be omitted if it is the same as in the previous  x,y  sequence.
For example, an applications program running on the host assuming a
4000 series terminal would send  HiY ,  LoY ,  HiX  and LoX  but not  Extra .
Notice, that  LoX  always needs to be sent. Notice also, that if either
Extra  or  HiX or both are sent,  LoY must  be sent.  To put it differently:
sending  HiY  is always optional.  LoY  can only be left out if neither
Extra  nor  HiX  are to be sent.  Again,  LoX  must always be sent.

In addition to these printable characters, the following control
characters and escape sequences are recognized.

  ESC             Introduce escape sequence.
  ESC   NUL       Introduce escape sequence.
  ESC   ENQ       Set bypass and return terminal
  BEL             Ring bell (flash screen).
  ESC   LF        Introduce escape sequence.
  CR              Set alpha mode and move to left margin
  ESC   FF        Erase and home.
  ESC   ETB       Make copy
  ESC   CAN       Set bypass condition.
  ESC   SUB       Set GIN mode and bypass condition.
  FS              Set point-plot mode.
  ESC   FS        Set point-plot mode.
  GS              Set vector mode 4
  ESC   GS        Set vector mode 4
  RS              Set incremental plot mode.
  ESC   RS        Set incremental plot mode.
  US              Set alpha mode.
  ESC   US        Set alpha mode.
  ESC   DEL       Introduce escape sequence.
  ESC  `          Set normal vector, pattern: 1111111111111111
  ESC  a          Set normal vector, pattern: 1010101010101010
  ESC  b          Set normal vector, pattern: 1111101011111010
  ESC  c          Set normal vector, pattern: 1110111011101110
  ESC  d          Set normal vector, pattern: 1111110011111100
  ESC  e          Set normal vector, pattern: 1111111101010101
  ESC  f          Set normal vector, pattern: 1111111100111100
  ESC  g          Set normal vector, pattern: 1111000011110000
  ESC  h          Set  bold  vector, pattern: 1111111111111111
  ESC  i          Set  bold  vector, pattern: 1010101010101010
  ESC  j          Set  bold  vector, pattern: 1111101011111010
  ESC  k          Set  bold  vector, pattern: 1110111011101110
  ESC  l          Set  bold  vector, pattern: 1111110011111100
  ESC  m          Set  bold  vector, pattern: 1111111101010101
  ESC  n          Set  bold  vector, pattern: 1111111100111100
  ESC  o          Set  bold  vector, pattern: 1111000011110000
  ESC  ?          Low Y coordinate


  Notes:
   1.     For a description of the report to the host see the section
            on reports to the host.
   2.     In  Extended  emulation  CR  is ignored in vector/marker mode
            for compatibility with Tektronix 4100 series terminals.
   3.     This sequence is not currently implemented.
   4.     After vector mode is entered, a move will be executed to the
            vector that follows.  All subsequent vectors will be drawn.
   5.     This escape sequence is recognized in vector mode as a
            replacement for the  DEL  character that some hosts cannot send.


   Incremental Plot mode

In incremental plot (marker) mode the following control and
escape sequences are recognized, as well as some printable characters.

  ESC             Introduce escape sequence.
  ESC   NUL       Introduce escape sequence.
  ESC   ENQ       Set bypass and return terminal
  ESC   BEL       Ring bell (flash screen).
  ESC   LF        Introduce escape sequence.
  CR              Set alpha mode and move to left  margin
  ESC   CR        Introduce escape sequence.
  ESC   FF        Enter alpha mode, erase and home.
  ESC   ETB       Make copy (note 3)
  ESC   CAN       Set bypass condition.
  ESC   ESC       Introduce escape sequence.
  ESC   SUB       Set GIN mode and bypass condition.
  FS              Set point-plot mode.
  ESC   FS        Set point-plot mode.
  GS              Set vector mode
  ESC   GS        Set vector mode
  US              Set alpha mode.
  ESC   US        Set alpha mode.
  SP              Turn beam off (pen up).
  P               Turn beam on (pen down).
  D               Move up (north).
  E               Move up, right (northeast).
  A               Move right (east).
  I               Move down, right (southeast).
  H               Move down (south).
  J               Move down, left (southwest).
  B               Move left (west).
  F               Move up, left (northwest).


  Notes:

   1.   For a description of the report to the host see the section
            on reports to the host.
   2.   In  Extended  emulation  CR  is ignored in incremental mode
            for compatibility with Tektronix 4100 series terminals.
   3.   This sequence is not currently implemented.
   4.   After vector mode is entered, a move will be executed to the vector
            that follows.   All subsequent vectors will be drawn.
   5.   These commands move the pen one (Tektronix) pixel. The
            actual amount of movement depends therefore on whether a
            1024 times 1024 coordinate system is used or a 4096 times 4096
            one.   This is controlled by the gadgets in the Incremental Mode
            area of the  Preferences  requester.


   GIN mode

When the Graphics INput (GIN) mode is set, also the bypass condition is
entered.  This means that keyboard and mouse actions are handled
internally by the Graphics Emulator and usually sent on to the host in
a different form.  GIN mode (and bypass condition) can be exited
transparently to the host by selecting the  Off  sub-item of the
Graphic Cursor  menu option, but is usually terminated by a report
to the host.  A report to the host is sent when any alphanumeric
character is entered from the keyboard, or when the left mouse button
is pressed.  For a description of the report see the section on reports
to the host.

During any bypass condition, the following escape and control
sequences are recognized:

  ESC   ENQ       Set bypass and return terminal status
  BEL             Clear bypass and ring bell (flash screen).
  ESC   BEL       Clear bypass and ring bell (flash screen).
  LF              Clear bypass and cause new line.
  ESC   LF        Clear bypass and introduce escape sequence.
  CR              Clear bypass, move cursor to left margin and enter alpha mode
  ESC   CR        Clear bypass and introduce escape sequence.
  ESC   FF        Clear bypass, enter alpha mode, erase and home.
  ESC   ETB       Make copy
  ESC   CAN       Set bypass condition.
  ESC   SUB       Set GIN mode and bypass condition.
  US              Clear bypass and set alpha mode.
  ESC   US        Clear bypass and set alpha mode.


  Notes:
    1.   For a description of the report to the host see the next
            section on reports to the host.
    2.   This sequence is not currently implemented.

   Reports to the host

There are several ways in which the host can request a report from the
Graphics Emulator.  The details depend on the nature of the request and
on the current graphics mode.

While the terminal is in alpha mode,  ESC   ENQ  received from
the host causes automatic transmission of the terminal status byte, the
x,y  position of the lower left-hand corner of the alpha (block)
cursor, and the end-of-report sequence.

When the terminal is in vector, marker or incremental plot mode,
ESC   ENQ  causes transmission of the terminal status byte,
the current  x,y  position of the beam (pen) and the end-of-report
sequence.

During GIN mode,  ESC   ENQ  leads to transmission of the x,y  position
of the graphic cursor and the end-of-report sequence. The Graphics Emulator
exits GIN mode and returns to alpha mode.

Also during GIN mode, entering a character on the keyboard or pressing
the left mouse button causes transmission of the entered character (or
in case the mouse button was pressed, the currently selected character
for that case, see the User's Manual), the  x,y  position of the
graphic cursor and the end-of-report sequence.

In the default case, where the  Use 4010/14 Report  gadget is selected
from the  Preferences  requester, the report has the following appearence:

  Status      Bit 0: always ``1''.
              Bit 1: ``0'' if left margin is at left, ``1'' if at center of
                     screen.
              Bit 2 and 3:  ``00'': mode is point plot.
                            ``01'': mode is alpha.
                            ``10'': mode is vector.
                            ``11'': mode is other.
              Bit 7: parity. This byte is sent first.
  HiX         Bit 0 through 4: most significant 5 bits of x coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  LoX         Bit 0 through 4: least significant 5 bits of x coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  HiY         Bit 0 through 4: most significant 5 bits of y coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  LoY         Bit 0 through 4: least significant 5 bits of y coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.

 End-of-report sequence.


If the  Use Extended Report  gadget is selected from the Cursor Report
Options  area of the  Preferences  requester, the report appears as:

  Status      Same as above.
  HiY         Bit 0 through 4: most significant 5 bits of y coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  Extra       Bit 0 and 1: least significant 2 bits of x coordinate.
              Bit 2 and 3: least significant 2 bits of y coordinate.
              Bit 4: unused.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  LoY         Bit 0 through 4: intermediate 5 bits of y coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  HiX         Bit 0 through 4: most significant 5 bits of x coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.
  LoX         Bit 0 through 4: intermediate 5 bits of x coordinate.
              Bit 5 and 6: ``01''.
              Bit 7: parity.

 End-of-report sequence.


In both cases, the end-of-report sequence is either non-existent or a
single  CR  or a  CR   EOT  sequence, depending on the currently selected
default (see also the User's Manual).

In  Extended  emulation mode some other sequences are recognized
that cause a report to be sent to host (see next section).

   Extended emulation

When  Extended  is selected from the  Emulation Options  area of
the  Preferences  requester, some control and escape sequences are
recognized that otherwise are not. The category of supermode-changing
control sequences was already discussed in section 1.

Additionally, the following escape sequences are recognized:

  ESC 0d     Draw light vectors with current attributes.
  ESC 1d     Draw dark vectors (erasing previously drawn graphics).
  ESC #!0    Request for report of current supermode.

The report generated is a 6-character sequence: %!000 CR  if the current
supermode is Tektronix, %!001 CR  if the current supermode is Alphanumeric.

ESC IQTG Request for report of the current color map.  The report has the
following syntax:   TG number of surfaces  report-integer array
CR , where  number of surfaces  is the report-integer 1, and  integer array
has the structure  color 0  surface number  color 1   color 2 ... color 7 .
The  surface number  is the report-integer -1, and the  color n  are
three-report-integer sequences describing hue, lightness and saturation
of color n. The length of the array is therefore 25 (specified as the first
number in the array as described in section 7.3) A report-integer in
this context is always a three-character sequence which is different from a
regular Tektronix integer, see section 7.2.

ESC LT string

Display the Tektronix 4100-series character string at the current position.

A 4100-series character string starts with a Tektronix 4100-series integer
(explained below) indicating the length of the string followed by the
string itself as printable ASCII characters.

ESC ML index  Switch to color index.   index is a Tektronix 4100 series
style integer in the range 0 through 15 (section 7.1).

ESC MV pattern

Switch to pattern  pattern .  pattern  is a Tektronix 4100
series style integer. The patterns are as described in section 3, in
the same sequence, n in the range 0 through 7.

ESC TG surface  colormap

Change the color values.   Hues, lightnesses and intensities of the new
colors  are specified in  colormap . The  surface  number has to be the
integer `1', and the  colormap  is a standard 4100-series array of integers
in the sequence  color-index ,  hue ,  lightness , saturation , next-
color-index   ... , as  explained below.

ESC WL0  Private sequence.

When this sequence is sent, the emulator will open a new capture file.

  Tektronix 4100-series standard integers

The encoding scheme of a standard Tektronix 4100-series integer
is syntactically described by:

  i  = [ HiI  [ HiI ]]  LoI

  Each item enclosed in [ ]  on the right hand side represents an
ASCII character:

  HiI         Bit 0 through 5: most significant 6 bits of integer.
              Bit 6: ``1'' (Tag bit).
              Bit 7: parity.
  LoI         Bit 0 through 3: least significant 4 bits of integer.
              Bit 4: sign bit. When set, the integer is positive.
              Bit 5 and 6: ``01'' (Tag bits).
              Bit 7: parity.

  In the syntactical expression above, an item enclosed in [ ]
may be omitted if the significant bits are 0. When two  HiI  values
are specified, the first one gives the bits 10 through 15 of the
resulting integer, the second one bits 4 through 9, and the  LoI
value bits 0 through 3. If only one  HiI  value is specified, it
determines bits 4 through 9. If only a  LoI  value is specified,
the resulting integer takes the value specified in the bits 0 through
3.  LoI  must always be sent, and its bit 4 determines the sign of
the integer.

Notice, that with this convention, the positive integers 0 through 9
happen to coincide with the ASCII characters `0' through `9'.

  Tektronix 4100-series report integers

The encoding scheme of a Tektronix 4100-series report integer is
different from that of a standard integer and is syntactically described by:

  i  = [ HiI1 ] [ HiI2 ] [  LoI  ]

  Each item enclosed in []   on the right hand side represents an
ASCII character:

  HiI1        Most significant 6 bits of integer plus 32.
              Bit 7: parity.
  HiI2        Middle 6 bits of integer plus 32.
              Bit 7: parity.
  LoI         Least significant 4 bits of integer.
              Bit 4: sign bit. When set, the integer is positive.
              Bit 7: parity.

Notice, that all three parts of the integer are always sent.

Notice also that decoding consists of subtracting 32 from the first two
characters, shifting the first by 6, adding the second, shifting the
result by 4, and adding the third after masking out the sign bit. If
the sign bit is set, the sign of the result is positive.

  Tektronix 4100 series integer arrays

A Tektronix 4100 series array of integers is syntactically
described as:

  array  = number-of-elements  int  ...  int

It is simply a list of N integers encoded as explained above,
preceded with the number N, also encoded as an integer.


   Table of ASCII control characters

The following is a table of the first 33 ASCII characters.


 dec.  hex. oct.    name        ctrl  equivalent



 0      0     0     NUL   ctrl  @
 1      1     1     SOH   ctrl  A
 2      2     2     STX   ctrl  B
 3      3     3     ETX   ctrl  C
 4      4     4     EOT   ctrl  D
 5      5     5     ENQ   ctrl  E
 6      6     6     ACK   ctrl  F
 7      7     7     BEL   ctrl  G
 8      8     10    BS    ctrl  H
 9      9     11    HT    ctrl  I
 10     A     12    LF    ctrl  J
 11     B     13    VT    ctrl  K
 12     C     14    FF    ctrl  L
 13     D     15    CR    ctrl  M
 14     E     16    SO    ctrl  N
 15     F     17    SI    ctrl  O
 16     10    20    DLE   ctrl  P
 17     11    21    DC1   ctrl  Q
 18     12    22    DC2   ctrl  R
 19     13    23    DC3   ctrl  S
 20     14    24    DC4   ctrl  T
 21     15    25    NAK   ctrl  U
 22     16    26    SYN   ctrl  V
 23     17    27    ETB   ctrl  W
 24     18    30    CAN   ctrl  X
 25     19    31    EM    ctrl  Y
 26     1A    32    SUB   ctrl  Z
 27     1B    33    ESC   ctrl  [
 28     1C    34    FS    ctrl  backslash
 29     1D    35    GS    ctrl  ]
 30     1E    36    RS    ctrl  ^
 31     1F    37    US    ctrl  _
 32     20    40    SP    space.